Skip to content

Tate-Wagtail project conventions

Git branching model

ⓘ The base branch is main. The production release branch is production.

⚠️ Never work directly on main or production

Ensure you've pulled the latest main and create a new branch from it, prefixed by a broad category and suffixed by the Trello card identifier if relevant: 

git checkout -b feature/extra-squiggles--aMb09znP
git checkout -b fix/newsletter-signup

Pull requests

  1. Push your branch to the remote when ready to merge
  2. Make merge (pull) requests on GitHub, merging into main
  3. Edit details as necessary
  4. Add peer reviewer if required
  5. If CI checks fail, fix these locally and push your branch again

Rebasing on main

Often, your working branch will go out of sync with the base branch, and you'll see this message on the pull request:

ⓘ This branch is out-of-date with the base branch
Merge the latest changes from main into this branch. …

To fix this, rebase your working branch on main and force push it:

git checkout main
git pull
git checkout <my-branch>
git rebase main
git push --force

If the rebase command causes merge conflicts, either follow the guidance, resolving the conflicts one by one via your favourite merge editor, or if you are confident your local changes are to be kept, abort the rebase and use the rebase strategy-option flag:

get rebase --abort
git rebase --strategy-option ours --no-commit main
git push --force

You should then be able to hit the 'Merge (squash)' button on the pull request.

Deployment Cycle

Once a branch has been merged into main, a GitHub Action will deploy it to the pre-prod environment. The feature/fix should be tested here, and once satisfied you can deploy to production (see deployment documentation).

Git commit message conventions

Commit title

  • Capitalise the first word
  • Use the imperative mood: 'Make the logo bigger', 'Fix the weirdness'
  • Keep the message under 50 characters
  • Be succinct

It should make sense to say: "If applied, my commit will [commit title]".

Rather than this: 

updated project conventions page to include new section on git commit messages and updated the section on git branching model

Do this: 

Update Git section of project conventions page

Commit body

In some cases, you might want to add more information than you can summarise in the title, which you can do in the commit body.

  • Separate the body from the title with a blank line
  • Wrap lines at around 70 characters
  • You may use hyphens - for bullet points

Commit message with body: 

Update Git section of project conventions page

This commit explains the branching model and adds guidance on commit
message conventions, including:

- Message title
- Message body

This example of the commit body shows that the imperative mood of the 
message title can be dropped. The focus should be on clearly explaining
what's being committed, if this can't be done in the message title.