Using Git and GitHub
Never push to the main branch! Code must always be reviewed first.
Workflow with Git and GitHub
Create an issue
If you haven’t already, file an issue that describes what you are doing - whether it be fixing a bug, adding a feature, or something else. Issues help to keep track of both the work to be done, and the work that has been done.
You should ensure that the issue is as detailed as possible as it may need to be picked up by someone else. Even if only you intend to work on the issue, over time it can be easy to forget things if there isn’t enough information. They can also help you to remember what changes you have made to your code, and why you had to make these changes, which can be useful if you need to provide change logs when you release your code.
Issues are a good record to explain what a PR is for. It’s also a useful area for input from other members of the team.
Create a branch
Once the issue is created and you have decided that you are going to work on it, first assign yourself to the issue in GitHub. This is an indication to others and helps to prevent multiple people from independently working on the same issue.
Once you have assigned yourself, you must make a new branch to work on that feature. GitHub offers a button to do this automatically on the issue page, on the right-hand side.
If you used the create branch button on GitHub it will automatically close the issue when merged.
Locally you can then work on the branch, pushing your code regularly to GitHub so it can be run and inspected when you are not around.
Write commits
All commits should be atomic, in short,
Each commit does one, and only one simple thing, that can be summed up in a simple sentence.
All of your commits should be in branches, the only changes that are made to the main branch would be via pull requests (PR) that have been reviewed by at minimum one colleague.
When you think that your changes are ready to be merged, it’s time to create a PR and request a code review.
Reviewing a PR
When you create a PR, you must do two things:
- Immediately make someone an assignee - this is the person who will merge the PR. Typically, this should be the person creating the PR (you)
- Select a person (or people) to review the PR
If your code is not yet ready to be merged then you should use a draft PR.
Note that draft PRs are only available on public GitHub repos.
Wait until the reviewer(s) has completed the review and marked it as ready to merge. At this point, the person who is assigned to the PR can complete the merge.
Most merges will be the default Create a merge commit but sometimes you may wish to Squash and merge. As the person requesting the PR, you can select whichever option is wanted from the drop-down in GitHub as part of the PR.
Reviewing methodology
By using this approach of the assignee completing the merge, it ensures that code quality is maintained and prevents code from being merged when it is not yet ready. For example, you may have started a PR thinking your work is complete, and a reviewer checks the code and agrees to merge, however, you may realise that there are still things to work on, or there are issues that need to be addressed.
The person who is assigned to the PR should be the only person making commits to the branch and this will prevent merge conflicts. If you wish for someone else to collaborate on the branch, then you should assign the PR to that person. At that point, they can pull your branch down and work on it, but you must stop using that branch locally.
Only one person should ever work on changes to a branch at any time, and it is important to communicate with colleagues so they know to pull the latest changes in.
If the PR is later assigned back to you then you must immediately pull changes.
There may be times when you cannot be the assignee on a PR and in those situations you should nominate someone else to be the assignee and in charge of the PR, the same rules as in the paragraph above would then apply.
If, as a reviewer, you find that no one is assigned to the branch, you should get in contact with the person who created the branch and decide who is going to be the assigned owner of the PR.
Outside collaborators
In circumstances where the person who created the PR is an outside collaborator and doesn’t have permission to merge, then the reviewer should also be the assignee. In these circumstances, the collaborator will be working from their local fork and will be the only person who can push to the branch. The reviewer, once happy to approve the changes, can merge the PR.
Preparing a package release of your code
We use semantic versioning.
Repository organisation
Each of the team’s repositories should have two assigned roles: owner and deputy.
The owner is likely to be the person who created the repository and/or has good knowledge of its content. The responsibility of the owner is to:
- have overall responsibility for quality
- triage issues, label them (especially ‘bug’ and ‘must’) and put into milestones
- tag and release the code and, if relevant, deploy it
- bring important issues to sprint by adding to backlog
- define how PRs are reviewed (e.g. issue/PR templates, CI Actions) and that they are reviewed
- ensure adequate testing is in place
- add and maintain the CODEOWNERS file
The deputy should perform these duties in the absence of the owner and provide updates to the owner on their return.
Further reading
See also our GitHub as a Team Sport presentation.