RFD 4

Using Git

Max Gallup Max Gallup
Elias Groot Elias Groot

Source management with git allows for ample opportunity of dangerous, unhelpful or plain annoying experiences as a software engineer. While this is bad enough when limited to shooting yourself in the foot, it gets far worse when shooting someone else's. To prevent any gunshots, we have drafted a list of guidelines to follow when working with git in our codebases.

Apply Conventional Commits

Conventional Commits bring structure to chaos. They provide value for humans to quickly grasp the purpose and effect of a given commit. Machines benefit too, as changelogs and version bumps can be automatically generated from this well-defined commit structure.

Limit yourself to using only feat:, fix:, and chore: as commit prefixes. When introducing a breaking change, use feat!:. When a commit indicates unfinished work, use wip:.

The things you can do with Convential Commits are truly useful and cool. There is also support for it by major OSS projects such as Google's Release Please Github action (though we prefer not to use this action anymore nowadays). We have built projects such as ASE in the past, that rely on Conventional Commits for automated version bumping and package releasing.

Treat Main as Production

Main should only contain production-ready code. Failing CI on main indicates that production is failing currently, or will be failing soon.

How successful this is, mostly depends on how strictly this is enforced. Flaky tests cause "CI failure fatigue" and it is always possible to ignore branch protection rules in case of an emergency. We should keep pointing each other out if we mistreat main.

Branch Early and Often

Except for main, branches should be short-lived and exactly correspond to work items from the project management software. Similar to commits, branch names should be structured as follows item-id/title/author.

  • item-id connects the branch to an issue tracked in the project management software. This means that a work item should be made before branching. For example, in plane one could make a work-item and give it a good description and time estimation. Then plane will give it a work-item id, so something like: SYNK-11

  • title is a short description of the work. For example: server-reboot

  • author is the first name of the team member doing the work. For example: max

Then, the resulting branch name would be SYNK-11/server-reboot/max.

When you feel like a branch cannot be captured into one work item, you should most likely branch further. When you feel like you can do a lot of work in one branch, you should most likely narrow down your work items.

Adhering to this guideline will not only make you a more beloved git user, it also trains your project management muscle. Scoping a work item correctly is hard, but you will get better at it over time!

Merge, don't Rebase

Merges show the point in time that feature branches were integrated into other branches, and eventually main. This is useful information to have when attempting to find the root of an issue, and should not be lost.

Don't Merge and Change

When you merge a branch into another, let that merge be its own commit so that everyone can see what merge decisions you made. If you have changes to make, do that before or after the merge commit, but not in the same commit.

Examples

The best examples are found in our existing code bases. Though, some examples are highlighted here.

Encouraged

Show how your work impacts the code base, and where one can find more information.

SYNK-11/failing-redirect-on-signup/elias
----
fix: changed the redirect URL to be based on the API-provided structure
feat: added unit tests to catch erroneous redirects
chore: removed unused environment variables

Point out breaking changes.

SYNK-13/sign-up-api-improvements/elias
----
wip: foundational work for supporting generic oauth
fix: support oauth providers that do not return any scopes
feat!: removed support for oauth1 providers

Do not present minor changes as changelog items.

SYNK-14/ui-stability-improvements/elias
----
chore: refactored frequently used functions into one
chore: added more descriptive comments to often-used functions

Discouraged

Omit branch types or commit prefixes.

stability-improvements
----
Moved /md to /docs
Removed oauth1 providers

Capture time, instead of work.

elias-monday-improvements
-----
chore: files still on my computer
feat: late monday push

Omit references to background knowledge and work items.

feature/api-improvements
-----
fix: implemented fix as talked about on the phone
feat: added new requested feature