point.free - Meta

Conventional Commits Change my Brain

2024-07-24T00:00:00+00:00

What is a conventional commit?</h2>

In case you’re not aware, conventional commits</a> is a standard format for writing commit summaries. It looks like this.

build(deps): bump git2 from 0.18.3 to 0.19.0
</span>
</span>Bumps [git2](https://github.com/rust-lang/git2-rs) from 0.18.3 to 0.19.0.
</span>- [Changelog](https://github.com/rust-lang/git2-rs/blob/master/CHANGELOG.md)
</span>- [Commits](https://github.com/rust-lang/git2-rs/compare/git2-0.18.3...git2-0.19.0)
</span>
</span>---
</span>updated-dependencies:
</span>- dependency-name: git2
</span>  dependency-type: direct:production
</span>  update-type: version-update:semver-minor
</span>...
</span>
</span>Signed-off-by: dependabot[bot] <support@github.com>
</span></code></pre>
This example is from dependabot</a>, which does
conform to conventional commits. Notice that only the first line, the commit
summary</em>, is part of the conventional commits spec here. The last line is a
“footer”[1]</a></sup>, or technically, a
trailer</em></a> added by the git commit -s</code> flag, -s</code> short for --signoff</code>.</p>
The exact spec looks like this:</p>
<type>[optional scope]: <description>
</span>
</span>[optional body]
</span>
</span>[optional footer(s)]
</span></code></pre>
Unlike many project specific standards, such as that of
angular</a> or nixpkgs</a>,
what sets conventional commits apart is that it aims to be a universal commit
standard, a bit like how semantic versioning</a> seeks to be
a universal software versioning standard.</p>
In the same sense as semantic versioning provides meaning through version
numbers, such as a major</code> number increasing meaning a breaking change,
conventional commits also seeks to encode information about the state of a
project in the commit summaries, and provides enough information to reasonably
tell when it’s time to do a patch, minor, or major version bump.</p>
It further also provides ways to specify if a commit contains a breaking change,
via a git footer.</p>
It may be easiest to explain this by just showing you the spec.</p>


The commit contains the following structural elements, to communicate intent
to the consumers of your library:</p>

fix:</strong> a commit of the type</em> fix</code> patches a bug in your codebase (this correlates with PATCH</code></a> in Semantic Versioning).</li>
feat:</strong> a commit of the type</em> feat</code> introduces a new feature to the codebase (this correlates with MINOR</code></a> in Semantic Versioning).</li>
BREAKING CHANGE:</strong> a commit that has a footer BREAKING CHANGE:</code>, or appends a !</code> after the type/scope, introduces a breaking API change (correlating with MAJOR</code></a> in Semantic Versioning).
A BREAKING CHANGE can be part of commits of any type</em>.</li>
types</em> other than fix:</code> and feat:</code> are allowed, for example @commitlint/config-conventional</a> (based on the Angular convention</a>) recommends build:</code>, chore:</code>,
ci:</code>, docs:</code>, style:</code>, refactor:</code>, perf:</code>, test:</code>, and others.</li>
footers</em> other than BREAKING CHANGE: <description></code> may be provided and follow a convention similar to
git trailer format</a>.</li>
</ol>
Additional types are not mandated by the Conventional Commits specification, and have no implicit effect in Semantic Versioning (unless they include a BREAKING CHANGE).</p>
A scope may be provided to a commit’s type, to provide additional contextual information and is contained within parenthesis, e.g., feat(parser): add ability to parse arrays</code>.</p>
</blockquote>

So basically, if there is a type fix</code>, that’s a PATCH</code> bump to your semver, a
feat</code> is a MINOR</code> bump, and a BREAKING CHANGE:</code> footer or a !</code> after the
type/scope is a MAJOR</code> bump.</p>
If we for instance have commit with the summary fix: change windows-only imports to be windows-only</code>, that’s a PATCH</code> change, and if we are on version
3.2.48</code>, then next version will have to be at least 3.2.49</code>.</p>
If we instead had a summary feat: add --no-|show-symlinks flags for filtering output</code>, then that would a MINOR</code> change, and again, if we were on 3.2.48</code>,
next release would be 3.3.0</code>.</p>
Lastly, if we had a summary feat(flags)!: add --classify=always,auto,never</code>,
even thou it has a feat</code> type, the !</code> indicates this is a breaking change, and
so we must cut a new MAJOR</code> version on next release if we include this commit,
meaning that if we were on 3.2.48</code>, we’d go to 4.0.0</code>.</p>
Yes. Breaking changes means a new major version. Yes, that might seem sever to
you if  you’re not used to being at the helm of something being used by a lot of
people, but that’s how we make these sausages (at least if we’re actually trying
to do it correctly). The guy who authored the semver spec, Tom
Preston-Werner</a> (also known for co-founding
GitHub</a> and creating gravatar</a>) has
a blog post about this called Major Version Numbers are Not
Sacred</a>.</p>
What people end up doing in practice is building up a lot of breaking changes
and then releasing them all at once, to not constantly destroy the API/ABI and
UX of their software. How this ties in with a more continuous development is a
very interesting question, e.g. how does
eza</a> manage to release a new version
every week, yet also work on breaking changes like config files or moving to a
new command line parser (specifically clap</a>).
I think such a discussion is far out of scope for this post, but I may write
about it in the future.</p>
Conventional Commits and Linguistic Relativity</h2>
If you were to ask wikipedia what “Behavioral Design” means, it would reply:</p>

Behavioural design is a sub-category of design, which is concerned with how
design can shape, or be used to influence human behaviour.</p>
</blockquote>
Now, how is that relevant to us as developers, maintainers, or just hobbyist
hackers?</p>
Well you see, the design of conventional commits, whether intentional or not,
has  a lot of decisions that end up shaping how contributors interact with your
project.</p>
When I initially forked eza</code>, I mostly moved us to conventional commits fairly
early because I was concerned with a maintenance burden. I knew that exa</code> had
been a project  of maintainer burnout, and what I was trying to do was create
longevity for the project. That meant that if there was something I could
offload to someone or something else, I would, including changelogs.</p>
And yes, conventional commits means I don’t have to write changelogs, I can
automate it, and it means  I don’t have to think too hard about what version is
next, it’s automatically generated. In fact, I can release eza every week
because  a release is just running two scripts, doing a cargo publish</code>, and a
nix-update eza</code> in the nixpkgs</a> repo and
opening a PR.</p>
While that release velocity is great, I found another, much more interesting
perk of using conventional commits. Namely that conventional commits lead  to
better commits, better commit summaries, better PRs, and better structured
commits.</p>
For instance, if a project just allows a commit summary to be an arbitrary
string, what you’ll often end up with is either something like made extensions work</code>, a single commit that  encompasses vast refactorings of the codebase,
introduces a feature, fixes 3 different bugs, and is one big monolithic and
unrevievable mess.</p>
On the other hand, it also saves you from the series of wip</code>, wip 2</code>,
formatted code and added quantum cryptography</code>, made compile</code>. These are
equally unreviewable, and completely destroy your git log.</p>
Now, you may have the discipline of projects like
nixpkgs</a> of  asking contributors to rebase
their commits, so that they each represent unique atomic changes. But even then,
what conventional commits gives you is a language to express what these changes actually are.</p>
Before I had conventional commits as something I could just write without
looking at the spec, I would genuinly struggle putting words to what my changes
did. It made it hard to create good PRs to projects.</p>
Now, it’s much easier. I just go:</p>

refactor(parser): used enums instead of bools in match logic</code></li>
fix(parser): capital letters not differentiated</code></li>
fix(parser): long lines ignored</code></li>
feat(parser): add long flags</code></li>
docs(parser): document long flag usage</code></li>
style: change flag rendering</code></li>
ci: check parser flags workflow</code></li>
</ul>
Not only does this make my PR much more structured, but by getting into that
habit, I find that  my work also becomes much more organized. Instead of just
working on some hodgepodge mix of things at the same  time and committing either
to save my work or to put all of it together in a disorganized sack of a single
commit, I find that I am much more able to dissect a problem into discrete
solvable steps.</p>
I’d even go as far as saying this makes you a better programmer, as breaking
down a large problem into small solvable chunks is a great problem solving
strategy.</p>
What conventional commits does is it gives you this language to describe the
steps it  takes to solve a problem, and getting familiar with that vocabulary
not only makes you a better programmer, but it makes it much easier to work with
you, and it heavily reduced the burden on maintainers.</p>
Linguistic relativity is the idea that the structure of a language influences
the speakers world view and cognition, changing how you interact with your
surroundings. Linguistic relativity is a hypothesis, but I find it pretty easy
to prove the weak case that if you can’t signify something, you will struggle to
operate with it.</p>
In other words, conventional commits get you merged faster, and makes your code
better. Hopefully you’re sold by this point.</p>


There are some tools for dealing with these, such as git-footers</a>. Personally, I don’t really use those. But it’s good to know they exist. ↩</a></p>
</li>
</ol>

Merge or Rebase 2024-05-29T13:40:00+00:00 This isn’t the article that’s gonna explain merge vs rebase for people that haven’t used git before (sorry). Rather, this is gonna be about some more meta things for maintainers, release engineers, and other people who care about development process. Git gives you a lot of options. How you use it isn’t prescribed in advance. There are a lot of ways that people might use git differently, but here, I’m more seeking to investigate some of the ways of using git that are relevant to people in charge of git repositories with a non-trivial amount of contributors, like myself. While I enjoy having these things done differently between projects I’m working in and part of maintaining — as it gives some diversity to the methods I get to use in my work, and let’s me continuously evaluate multiple methods[1]</a> in practice — I do think it makes sense that for a single project, there is consistency in the way it’s developed, so that expectations can be set, and procedures can be learned and become second nature. There are two main questions for a project to decide when it comes to merging via git. How to merge feature branch changes from PRs.</li> How to merge newest changes into outdated branches.</li> </ol> I’ll discuss both, and then summariese my observations. Merging branches</h2> When some developer starts working on a software feature, especially in open source, those changes, typicall, will be made in a separate branch that has branched off from the main branch. This is often called a feature branch. This allows the developer to work on their feature in isolation, and, at some point, put those changes back into the main branch, for all people to use. This is what some may call trunk based development, although the lines get fuzzy about how long a PR should live. That discussion is out of scope for this post, but I’d love to follow up with a post about that at some point. When moving changes from your feature branch into main, you can have potentially three possible options for merging. Fast Forward</li> Rebase and Fast Forward</li> Merge</li> </ul> For fast forward, main may not have changed while you were working, and so you can “fast forward” your changes on top of main, without having to worry about any conflicts. This is, for both developers and maintainers, extremely easy, with some reservations that will be discussed later. Another option is to take the changes from the updated main branch, and git pull --rebase origin main</code> them into your feature branch, placing your changes on top of the latest changes from main. As you may guess, this allows you to git merge --ff-only</code> your changes into the main branch. The final strategy is the classical merge. You may decide to merge your changes, and the changes in main together, using a special commit that represents the operation of merging the two together, a merge commit. Such a commit has special properties, such as having two parents, and being the result of the unification of two separate branches. Of course, if you’re not doing just a simple fast forward, either a rebase-ff or merge may require that you solve potential code conflicts. For instance, someone may have changed a line that you have also changed, leading to the two versions colliding. For the merge, you resolve this by making the merge commit define the merged version, for a rebase, you’ll go through your changes and adjust them so they fit cleanly onto the branch you’re pulling. One important difference to note for us, is between the two, merging into main typically gets done by the maintainer, where as rebasing gets done by the developer working on the feature branch. Rebasing also has some downsides. For example, if the person rebasing doesn’t have the PGP private key of the people who’s commit are included in the rebase, they cannot sign the commits. This means that if Alice made 3 commits and signed them with her PGP signature, Bob can’t later rebase those changes onto some other commit without breaking that signature. This is because, while the code doesn’t change, the commit revision does, and so the signature is wrong. Merging does not have this issue, as a merge is simply the actual merge commit, containing the new state of the branch, that potentially specifies how to rearrange everything so as to not cause any conflicts. Thus it doesn’t suffer from breaking the signatures. Now, if you’re using rebase for merges into main, as we do in eza, you may still want a signature verifying that a trusted person has indeed verified these changes are up to whatever standard they guarantee (eza at best guarantees that it runs on my linux box that you should be able to install it on NixOS[2]</a>). The way we solve this is by tagging all our releases with a signed tag, making sure you know that I’ve personally said that this is the codebase I want you to run for a given release. But even then, it’s coping. It’s not as nice as having a tree full of the signatures of everyone that’s committed, right on their commits. Another point raised against rebases is they rewrite history. This is true, unlike a merge that just merges two branches and keeps both in history, the rebase will make it appear as thou the feature branch was developed on top of the main branch. I don’t personally think this is a huge concern, except the loss of potential pretty git log --graph</code> outputs. One of the annoyances of merges, in comparison, is that they’re very noisy. Consider this output from nixpkgs: git log --oneline bfb7a882678e Merge pull request #314109 from trofi/githooks.tests-fix-eval 47bdef656cc5 Merge pull request #311260 from purepani/update-svelte-language-tools fc165a03b23a Merge pull request #309524 from r-ryantm/auto-update/enet 3de810d52cbe Merge pull request #309724 from r-ryantm/auto-update/secp256k1 1d6a2f5a4d4d Merge pull request #309787 from r-ryantm/auto-update/python311Packages.minio a36fa5451c44 Merge pull request #309426 from Rconybea/add-sphinxcontrib-ditaa 890f8e436a56 Merge pull request #309476 from r-ryantm/auto-update/goperf dfa36c1d67f5 Merge pull request #312557 from r-ryantm/auto-update/intune-portal 7d8ed5ce921d Merge pull request #291853 from greaka/grafana d0a20d7c5955 Merge pull request #314112 from khaneliman/bicep 4d2462511f06 Merge pull request #314099 from mrkline/snapper-and-borgbackup-doc-fix 3e3ac0e7baa8 Merge pull request #305516 from OPNA2608/init/lomiri/ayatana-indicator-display a46ce7c77d9d svelte-language-server: convert to buildNpmPackage 7962cbb2326b Merge pull request #314082 from superherointj/bicep-0.27.1 5771dbfa7d2f bicep: fix updater script 2db4e7d035f8 Merge pull request #313729 from pluiedev/zhf-24.05/gobang 44744fc83f3c githooks.tests: fix eval 0f3add331c6a segger-jlink: 794l -> 796b </code></pre> This… isn’t nice, and makes history way harder to read. Compare to eza: git log --oneline 22dbeec2 (HEAD -> main, origin/main, origin/HEAD) build(deps): bump libc from 0.2.154 to 0.2.155 82e4f0f3 build(deps): bump trycmd from 0.15.1 to 0.15.2 bbede6d4 (tag: v0.18.16) chore: release eza v0.18.16 70891fa1 docs(README): use 3 columns for packaging status badge e8e0b6da fix: change windows-only imports to be windows-only 15528d8b docs(install): fix typo in `INSTALL.md` 26e5943a docs: update INSTALL.md 20241984 build(deps): bump DeterminateSystems/nix-installer-action from 10 to 11 feff970d docs(man): replace decay with color-scale a1c36389 build(deps): bump DeterminateSystems/flake-checker-action from 5 to 7 7437c2a1 (tag: v0.18.15) chore: release eza v0.18.15 f1ef455b feat(devtools): add optional tag argument to deb-package.sh 23502d3c fix(devtools): correct command for latest tag in deb-package.sh 292cf7ec feat(devtools): return to original commit at the end of deb-package.sh 4f542eaf docs(reaedme): add some keywords for benefit of ctrl-f 6d6612d2 docs(readme): move heading out of collapsed section abe9f587 docs(readme): correct heading levels in markdown 01a9c2aa docs(readme): add how to find man pages in terminal and online. Partly fixes #967 f78e4bb6 (tag: v0.18.14) chore: release eza v0.18.14 01919cdd build(deps): bump palette from 0.7.5 to 0.7.6 414f70ba build(deps): bump unicode-width from 0.1.11 to 0.1.12 1554472a build(deps): bump libc from 0.2.153 to 0.2.154 bebd39c0 build(deps): bump uzers from 0.11.3 to 0.12.0 df7d51fc feat: add icon for "cron.minutely" directory 8b7dc5f5 (tag: v0.18.13) chore: release eza v0.18.13 c0df8ecd feat: generate completion/manpage tarballs on release 8afb5cc2 (tag: v0.18.12) fix: checking for deref flag in file_name a4782d1d feat: add scheme filetype and icons 87b36785 fix: allow unused imports for freebsd 99562e3a (tag: v0.18.11) chore: release eza v0.18.11 07f67708 fix: build aarch64, arm without libgit2 17733e9a fix(netbsd): enable the rule only for NetBSD. 7664a1fb ci: bump NetBSD version to 10.0 462fc344 fix(netbsd): fix clippy lints 75f1f8cf (tag: v0.18.10) chore: release eza v0.18.10 </code></pre> Isn’t that a lot nicer? I think so. Of course, what may be lost is that it’s no longer obvious from what PR a change originated. It also isn’t obvious to me when some feature branch was created, how long it was worked on and so on. This isn’t… really that important either, but it’s nice to have in logs. But you can just look at branches if you need to know this for tooling or something. For nixpkgs, you get a to have a visual overview of how branches end up in main. It looks like this: git log --oneline --graph * 4d4571b20a29 (HEAD -> devpi-loadcredential) nixos/devpi-server: fix loading credentials as DynamicUser * bfb7a882678e Merge pull request #314109 from trofi/githooks.tests-fix-eval |\ | * 44744fc83f3c githooks.tests: fix eval * | 47bdef656cc5 Merge pull request #311260 from purepani/update-svelte-language-tools |\ \ | * | a46ce7c77d9d svelte-language-server: convert to buildNpmPackage * | | fc165a03b23a Merge pull request #309524 from r-ryantm/auto-update/enet |\ \ \ | * | | 8e729c70a119 enet: 1.3.17 -> 1.3.18 * | | | 3de810d52cbe Merge pull request #309724 from r-ryantm/auto-update/secp256k1 |\ \ \ \ | * | | | f96a90834c5e secp256k1: 0.4.1 -> 0.5.0 * | | | | 1d6a2f5a4d4d Merge pull request #309787 from r-ryantm/auto-update/python311Packages.minio |\ \ \ \ \ | * | | | | 24d453186792 python311Packages.minio: 7.2.6 -> 7.2.7 * | | | | | a36fa5451c44 Merge pull request #309426 from Rconybea/add-sphinxcontrib-ditaa |\ \ \ \ \ \ | * | | | | | 197d6261ebf8 python311Packages.sphinxcontrib-ditaa: init at 1.0.2 | * | | | | | 51de558f5634 maintainers: add rconybea * | | | | | | 890f8e436a56 Merge pull request #309476 from r-ryantm/auto-update/goperf |\ \ \ \ \ \ \ | * | | | | | | 8eea66b3f69a goperf: 0-unstable-2023-11-08 -> 0-unstable-2024-05-10 * | | | | | | | dfa36c1d67f5 Merge pull request #312557 from r-ryantm/auto-update/intune-portal |\ \ \ \ \ \ \ \ | * | | | | | | | 010c4a334eaf intune-portal: 1.2404.23-jammy -> 1.2404.25-jammy * | | | | | | | | 7d8ed5ce921d Merge pull request #291853 from greaka/grafana |\ \ \ \ \ \ \ \ \ | * | | | | | | | | 254dbdcc6296 grafanaPlugins.grafana-oncall-app: init at 1.5.1 | * | | | | | | | | 0e5f44658ee6 maintainers/team-list: add fslabs | * | | | | | | | | 8d6f8c9ed75a maintainers: add lpostula | * | | | | | | | | 7bda925dacb2 maintainers: add greaka * | | | | | | | | | d0a20d7c5955 Merge pull request #314112 from khaneliman/bicep </code></pre> Another problem worth considering is that a rebase may — as Astrid</a> pointed out — results in main being in a state where a git bisect</code> of a build command may fail, if you haven’t ensured that all commits in the feature branch still worked after being rebased on top of the latest main. Now this is rare, but rare isn’t really a good argument for not caring here, as breaking once would be extremely annoying for people working on a bugfix, leading to false git dissect</code> positives. There are solutions to this. You could (perhaps) have each commit in a branch run against CI. This may be outside of your compute budget thou. Another option is to run your build command, e.g. cargo build</code> on each commit after a rebase, but then, this kind of checking step usually falls on the maintainer, and we, as maintainers, should seek to limit our own burdens as much as possible (to prevent burnout[3]</a>, the killer of most FOSS projects). To eza, this isn’t fatal, but a very interesting point worth keeping in mind. Updating a branch</h2> Of course, since there may be multiple people all working on separate branches, there is another problem. One person might have worked on something, at the same time as you worked on something else, and then gotten their changes merged before you had a chance. But if that happens, your changes might now conflict with what was in the main branch when you started, and worse, their changes may make ruin your work, or even make it unable to compile! The first choice a project should make, is whether or not to allow outdated feature branches to be merged. The problem with tolerating outdated branches is you will not be able to fix any problems related to integrating the code with the main codebase before merging it. This puts the burden of ensuring the code works on the maintainer, rather than the developer, and this is bad! If you do choose to not allow this, another question faces you: how should the main branch be merged into the feature branch when the feature branch is out of date with the main branch. Your options are either to merge the main branch into your feature branch, or to rebase your changes on top of main, making it like if you had started working on the latest changes. To me, it’s a more simple dilemma, merges shouldn’t exist if they don’t meaningfully represent merging two things together. Simply updating your branch is what rebase does best, and having merges both from feature branches into main and from main into your feature branch is absolutely tasteless. This clutters your history for no reason. It also makes it harder for you to fix your commits when the reviewer tells you that you had a faulty commit 3 commits before you merged main into your feature branch and kept working for 4 more commits. In general, rebasing with merge commits is tedious, and we only consider merges viable for the main branch under the premise that we won’t later need to rebase main, because everything that gets into main is in a state of being up to standard. Sadly, code forges lack a feature to only allow updating branches with the projects preferred standard, unlike for merges where rebase, squash, and merge are all options, that all can be disabled by the repositories owner(s). Summary</h2> So what where the tradeoffs? Merging feature branches into main Merges. Preserves history.</li> Gives you git log --graph</code>.</li> Doesn’t break PGP signatures.</li> Creates ugly git log</code>.</li> Gives weak protection that all commits build (if you have CI)</li> Puts burden of verification on maintainer.</li> </ul> </li> Rebase. Rewrites history.</li> No git log --graph</code>.</li> Breaks PGP signatures.</li> Creates useful git log</code> output.</li> Needs more care if you want all commits to be validated.</li> Puts burden of verification on committer (mostly).</li> </ul> </li> Fast Forward. Like a rebase, but with less drawback.</li> </ul> </li> </ul> </li> Updating your feature branch. Merges. merges make git rebase -i</code> difficult, when asked to change your commits.</li> It makes your git log</code> unreadable.</li> Doesn’t provide any benefits.</li> Mostly just a quirk that git even allows this, it doesn’t make sense.</li> </ul> </li> Rebase. The preffered choice.</li> Fits like a glove for updating your feature branch.</li> </ul> </li> </ul> </li> </ul> As a maintainer, remember that what where really trying to do if offload any non-maintainer burdens onto relavant roles, like developers and reviewers. We may wear multiple hats, often we are the final reviewers, but even then, it shouldn’t be our job to ensure a clean merge, we should meerly verify it. The main goal is always: maintainers shouldn’t need to fix the feature branch! This also applies for formatters. I personally mostly use alejandra for nix, but dayjob uses nixfmt (the RFC 166 version). I just hit a format button before commiting anyways, so it’s just cool to see the different options and feel out which ones I truly prefer. ↩</a> </li> Because I don’t have any MacOS, Windows, or BSD boxes to test on, and we don’t have any maintainers that do with the spoons to be involved in giving such guarantees. ↩</a> </li> Consider reading this excellent resource https://opensource.guide/maintaining-balance-for-open-source-maintainers/</a>, and this mozilla worksheet https://docs.google.com/document/d/1esQQBJXQi1x_-1AcRVPiCRAEQYO4Qlvali0ylCvKa_s/edit?pli=1#heading=h.xd8n2v3f4866</a>. ↩</a> </li> </ol>

point.free - Meta

Conventional Commits Change my Brain

Merge or Rebase

Summary</h2> So what where the tradeoffs?</p>