Conventional commits and CHANGELOGs
One of the things that I've done since joining my current team is to implement a standard approach for our commit messages.
We're using the Conventional Commits specification, which gives some additional rules to follow when writing commit messages.
For example:
build(deps): update Drupal to 9.4.5
Updated Drupal's `drupal/core-*` packages to 9.4.5.
See https://www.drupal.org/project/drupal/releases/9.4.5.
Refs: #123
We can see that this is a build task that relates to our project dependencies, in this example, we're updating Drupal core. We can also see this in the subject line.
In the commit body, I add as much information as possible to do with the change and include any relevant links, just in case I need to refer to them again, and the list the names of anyone else who worked with me. I also typically include any ticket numbers or links in the commit footer.
So far, I've mostly used the build, chore, ci, docs and refactor commit types, which are types that are recommended and used by the Angular convention.
Following this standard means that it's very easy to look at the Git log and see what type of changes are going to be included within a release and, if you're using scopes, which part of the application are affected.
Conventional commits also works nicely with something else that we've introduced, which is a CHANGELOG file.
There are tools that can generate and update CHANGELOGs automatically from conventional commits, but so far, we've been following the Keep a Changelog format.
It's easy to match the commits to the Added, Changed or Fixed types, and although it needs to be updated manually, it's easy to add to the Unreleased section of the file and re-organise everything within the appropriate headings as needed as part of a release.
What I like about this format is that it's more human-friendly and gives a higher level overview of the changes rather than a reformatted Git log.
As we do trunk-based development and continuous integration on our projects, there can be numerous commits related to the same change, so I'd rather only see a single line in the CHANGELOG for each change. This also makes it easier to share the CHANGELOG file with others, and we can still view and grep the Git log to see the individual commits if we need to.
- Oliver
