Version Control

Table of contents

Overview
Git config
Merges and Rebases
Feature branches
Pull Requests
Commits
Commit messages
Useful tools

Overview

Good git commit and repository hygiene¹ is a non-negotiable requirement to work efficiently and professionally. Having an excellent public git history² is essential for any non-trivial project where multiple developer collaborate.

Git config

Ensure your global .gitconfig file has the following entry. It ensure that a git pull rebases local changes. See Merges and Rebases below.

[pull]
  rebase = true

Also ensure that your user.name and user.email is correctly configured.

Merges and Rebases

Merges are strictly verboden³.
Synchronising a feature branch with the main branch must⁴ be done with git rebase. For an excellent explanation of merges vs rebases, see this tutorial by atlassion. A quick and to the point article on how to do it can be found here.

Feature branches

Feature branches are ephemeral⁵.
Rewriting, restructuring and splitting of commits are encouraged.
A commit must not⁴ introduce a bug in one commit which is fixed in a later, subsequent commit. Instead, the fixup commit should be merged into the offending commit by performing an interactive rebase.
The name used for a feature branch should⁴ be prefixed with your name, plus the first letter of your surname. For example, John Doe would use johnd/XYZ. The identifier post the prefix (XYZ here) must⁴ be concise, all lower-case, kebab-case, with words/concepts i.e. johnd/update-dependencies.
Introducing, updating and removing npm packages should⁴ be done as separate commits, not interleaved with the code that uses it. This is to help you (or others) when resolving conflicts on rebase that affect package.json and pnpm-lock.yaml files. An exception to this rule would include (but not limited to) upgrading a package that has introduced breaking changes.

Pull Requests

Feature branches must⁴ be submitted for review with a Pull Request on GitHub.
Pull Requests should⁴ be linked to a pre-existing issue in GitHub (ZenHub), unless its a fix/change that doesn’t have an issue. This should not be or become standard practice.
Pull Requests must not include a size estimate if it is linked to an existing GitHub issue, only if it is issue-less.
The PR branch must have a good public history² before a review is requested.

Commits

Commits should⁴ be as small as possible, yet be atomic⁶. Why?
- It makes the reviewer’s life a little more bearable
- Reverting the commit could be easier. This is not always the case as there may be dependencies between commits. Nevertheless, it is still good practice.
Commits must not⁴ introduce a test-case breakage in one commit and fix it in a subsequent commit.
Commits should⁴ follow a logical order.

Commit messages

All commit messages must⁴ follow the Conventional Commits specification. Here is a cheatsheet for easy reference. This should become habit relatively quickly.
Commit messages must not⁴ use the scope aspect of Conventional Commits. For example a commit message: fix(somescope): some message is not acceptable, whereas fix: some message is.
All npm based repositories have a cz command to invoke commitizen, which can assist in authoring your commit messages.
Use lower-case sentences in your commit messages. Use your judgement to determine if something needs to use a different case. For example, referencing a class AuthService should use the canonical PascalCase⁷ name.

Useful tools

forgit The grb shortcut is super useful to perform an interactive rebase.