Git Workflow Policy / Process

Keep your repos and github up to date

Daily synchronisation habit for all developers:

Enabling gsync

In terminal:

cd ~
nano .bashrc

Add the following scripts to the end of .bashrc:

export WINTERWELL_HOME="~/winterwell"
export PATH=$WINTERWELL_HOME/code/script:$PATH

You should be able to use gsync in new terminal window afterwards.

Using gsync

Shared web-app js/css code: wwappbase.js

Note: we have tried other approaches like git modules and npm packages. They were a bit painful.

Feature Branches and Pull Requests

Work should be done via:

  1. Make a ticket and talk to Dan (CTO) and Lauren (Sprint Manager).
  2. Make a branch and switch to it.
  3. Work in the branch.
  4. Create a pull-request (PR) and assign one of your colleagues as a reviewer.
  5. The reviewer does a code-review, then asks for edits or makes the merge when satisfied.

Pull-requests (PRs) help to make code-reviews part of normal working. That is good for catching bugs, for sharing knowledge around the team, and for writing better code.

Peer review can be skipped in urgent situations - but only when the cost of delay outweighs the risk of bugs in the relevant code. If in doubt, ask the CTO or the Sprint Manager.

Beware of Long-lived Branches!

Branches are great for safe development and code review. However having multiple branches on the go can lead to bugs and confusion. Issues caused by keeping branches are:

So avoid letting feature branches stay open for a long time (e.g. over a month is too long). A branch should be opened, worked on, then merged into master via a PR.

It is OK for the master branch to hold unfinished code, provided it isn't going to block other people. You can merge partly-done work into master.

When you create a branch:

When you finish a task:

Branch names: feature or bugfix/year-month/keywords

When you start a new task, make a new branch, e.g.:

git checkout -b feature/2022-09/my-shiny-feature
git push

Git will then give you a set-upstream command to run - do that.

Master and release branches

The master branch is the latest plausible code. You can expect it to mostly work. But you can also expect it to have bugs.

We create branches from master when we have a release-candidate. These are called release/{year}-{month}. The release branches should be stable and bug-free. Only tested code goes into a release branch.

Bug-fixes should be applied to master first, then back-ported (e.g. via cherry-pick) to the release branch. Very rarely should code be written on a release branch -- it's too easy to forget to port the edit back to master, and so lose a bugfix.