/content as a Hugo module to track linear history

[juliamrch]

This documentation contributing process is supposed to be easy and quick, to obtain an always updated doc. This is why we made a new repository on GitHub to host the whole site, and we wanted to preserve the history of the site presenting the doc to enable future maintainers to work easily on it as well.

The problem

This PR would fix the history tracking issue from old repository. Since we wanted a clonable site that contributors could test locally and deploy from GitHub to review apps on Clever Cloud, we couldn't find a solution to preserve both the building site history and the /content one. We wanted to avoid Git submodules, as we could see the learning curve for new contributors who never use them could be dissuasive.

This solution doesn't change anything for contributors, but maintain the +10 years linear history of /content/.

The solution

The /content/ folder is still in this project, but has its own history thanks to a .git history of its own. It's managed as a Hugo module, simpler to enable than Git submodules and doesn't need any cloning. The Markdown content repository is now referenced as a Hugo module, which allows the site to deploy even if its /content folder was empty (backup, yay). It's updated by a Git hook every time a push is done at the root of this project from a doc admin's machine.

Updating hook process

Every time a branch is merged into main, I pull changes on local and push changes to our private GitLab linked to the prod site by a pipeline. Pulling last commits will trigger a hook on my local repo (hooks aren't pushed by design and stay in the local repo).

Before any push on my part, the hook will:

1. check if any commit since the last push modified the /content directory
2. navigate to the root of the /content folder
3. check if the current branch exists, and create it if not
4. pull changes from main
5. cherry-pick commits affecting /content
6. push to the repo module

If approved, this .git/hooks/pre-push script should be added to the doc wiki for any new admin with access to the prod repo :

#!/bin/sh
# pre-push

# This script allows to push changes from the root directory to the content module directory.

# Get the name of the branch being pushed
branch=$(git rev-parse --abbrev-ref HEAD)

# Check if any commit since the last push modified the /content directory
if git diff --name-only origin/$branch..HEAD | grep "^content/"
then
  # Navigate to the content directory
  cd content

  # Check if the branch exists on the remote
  if ! git show-ref --verify --quiet refs/remotes/origin/$branch; then
    # If the branch doesn't exist on the remote, create it
    git checkout -b $branch
  fi

  # Pull the latest changes from the root project
  git pull origin $branch --no-rebase

  # Get the commits that affect /content
  content_commits=$(git log --pretty=format:"%h" origin/$branch..HEAD -- content/)

  # Cherry-pick the content commits
  for commit in $content_commits; do
    git cherry-pick $commit
  done

  # Push the changes to the remote repository
  git push origin $branch
fi

Miscellaneous

Added details imported from old project's Readme as well.

[github-actions]

Deployment has finished 👁️👄👁️ Your app is available here

[juliamrch]

Remembered you couldn't see my script so added it to the description 🙈

[juliamrch]

This solution doesn't satisfy the requirements and needs further research. I've tried several ways of including commits affecting /content but cherry-picking from the root history doesn't work very well and rewrites module's history when merging.

The easiest way to update is to commit any new change and push to the repo's module, but then we end up with something like that:

The history isn't the real one. In any case, one history will be rewritten at he end of the merge. I'm closing this PR to come up with a better solution.

[github-actions]

Your review app has been deleted 👋