10 things we should not compromise on with git-based collaboration

Over the years, the usage of version control had quite the interesting path — ranging from projects that did not even use git and distributed code on USB keys, to SVN, to find the ecosystem kind of settling on git and a somewhat standardised version of git flow.

Git flow

In theory it all works great — you use proper git flow, a develop, master, feature branches, hotfix branches, you know the drill. You release via CI (Continuous integration) with e.g. github actions, either from master or develop. You do pull request reviews. You employ semver for versioning. But in practice it can turn into a bit of a wild west.

Why is that though? One example would be because there’s a small enough number of developers that it can. It is especially evident on smaller open source projects which stem from being somebody’s afternoon hobby. The issue at hand is that even if you develop the project alone and publish it on e.g. npm (or any other package manager), there will potentially be thousands of users and proper development practices matter a great deal.

The excuse is usually time. With large and distributed teams, it forces you to use these rules. Coincidentally, you usually have more time with larger teams and larger projects. But with small(er) teams, there’s usually a lot of compromise. However, there are not a whole lot of time-gaining benefits stemming from those compromises, usually quite the opposite. Bugs become hard to track down where exactly they originated from, developers spend hours and hours working on merge conflicts, releases are impossible to track.

So here’s a list of things I think one should not compromise on, regardless of the time constraints of the project.

1. Having a stable master or release branch from which production deploys are made. More often than not, one ends up releasing to production from develop.
2. Proper versioning. One should make the effort to distinguish what requires a major version bump, what requires a minor version bump, and what only requires a hotfix version bump. One should also read the semver docs and actually employ it in practice. (One should never release different code under the same version number)
3. Proper release notes. It should be distinguishable which pull requests are in which release number and who wrote the PR.
4. Meaningful branch names and meaningful PR names. For branches, such as hotfix/something, chore/something, feature/something. PR names should also reflect whether it was a hotfix, chore or a feature. And no, feature/ticket-123 is not a proper branch name. It should contain some contextual name, even if it alongside contains the ticket number.
5. Dependencies cross reference. If a frontend (either mobile, web or desktop, doesn’t matter) release is made, the backend release it was based upon should be noted in the release notes, even if backend is backwards compatible at all times.
6. Deployments from master / develop / release branches only. It does occasionally happen that you don’t want to flood the repository with PRs and you just deploy from a feature / hotfix branch, but most of the time, it’s just not needed. God forbid there’s database migrations involved in those from-branch releases.
7. Not making PR reviews into a weird courtesy checkmark ritual. If you’re consistently not getting any useful feedback in PR reviews, something is wrong with the flow. If you’re constantly waiting for PR reviews to be made, something is also wrong with the flow.
8. Lint and enforce linting your code. But be sensible about it. There are rules nobody cares about. Think about which rules bring value to the project and those which are really just bloat and a time waster.
9. Writing some tests. But once again being sensible about it. There’s a sweet spot between spending too much and too little time developing the tests.
10. Last but not least — if there is an open source package that already does what you need for your next feature, don’t be like any other junior developer excited to jump at new things — take it. If needed, take it and make it your own. You’ll know when it’s time to write your own. Most of the time, it’s not.

The list could go on. But if you stick to those 10, I’m sure your projects will be neat and nice to work on.

Leave a comment if you can think of something else!