Github Branches

Making Changes

Changes should be made in small incremental steps following a branch-per-feature model. If the feature is going to take several sprints, consider breaking it down into smaller features. This avoids big ugly merges and keeps the team synchronized to the same code base. When the change is complete, a Pull Request is used to merge the change back into main.

1. Work on a branch

Perform code changes on a branch. Commit changes to your branch in small logical steps. Make commit comments brief but descriptive (“changed code” is useless to anyone else). Push your branch to the remote (GitHub) so that others can follow your changes and help if need be.

2. Sync your branch with main and test

When your changes are done, check that they are compatible with the latest changes on main. This is done by merging main into your branch and then testing. Address any merge conflicts on your branch. For larger changes, sync with main regularly, perhaps every day.

Test that your changes haven’t broken anything. Test that your changes work as expected. When done, make sure all your changes have been pushed to the remote branch.

TODO - call out the minimum tests to run for regression (we need a smoke test or maybe unit tests can do this)

3. Create pull request

Using GitHub, create a Pull Request (PR) to merge your branch into main. GitHub will warn you if the changes cannot be merged. If that happens, go back and sync your branch with main.

Assign someone from the team as a reviewer of the PR. Include in the PR notes about what changed (link to Jira task), how to test it, what to look for, etc. GitHub should notify the reviewer that they have been assigned by email. It’s a good practice to also send them a message on Slack.

The reviewer will independently test your changes, review code and provide feedback. When the PR is created, an automated build will also run a set of tests. To resolve issues, make changes on your local branch and commit, sync and push to the remote. GitHub will automatically detect the push and restart automated tests.

The reviewer, when satisfied, will approve the PR and merge changes into main (there’s a button for this).

TODO - we may care more about the git history given the repo is public. provide recommendations on how to make the history clean (ex: squashing merges / rebasing instead of simple merges)

4. Clean up

When the PR is complete delete the remote branch on GitHub. It is also good practice to clean up your local workspace by removing the remote tracking branches (git pull –prune) and deleting the local branch (git branch -d my_branch).