AGP 22: Introducing commit message conventions across Aragon projects

0x-r4bbit commented 6 years ago

Goals

This AGP's goal is to support a possible changelog strategy for Aragon projects by using automated tooling that relies on commit message conventions.

Therefore:

finding consensus on using commit message conventions across Aragon projects
ideally decision making for a convention

are needed.

Description

In order to implement https://github.com/aragon/aragonOS/issues/180 Aragon projects could rely on tooling to automatically generate changelogs from the project commit histories. There are basically two parts to make this work:

Commit Message Convention A convention or format of the commit message that can be parsed and then output in another arbitrary format that can be consumed as changelogs.
Tooling A tool that knows how to read commits from a Git repository, parse the commits and creates a dedicated output that could essentially be a changelog.

Tools for this strategy do already exist and are battle-tested in real-world project for many years. The Angular projects for example introduced semantic commits + conventions in order to generate changelogs, for the first time in the JavaScript space. Another example can be seen here in the MachineLabs project, which happens to be a mono repository with multiple sub packages. The linked file gives an idea of what a changelog could look like.

Automated changelogs introduce some nice properties as well:

More awareness in the importance of "good" commit messages (contributors will send pull requests with well-defined commit messages)
Commit(s) (histories) are easier to read, follow and work with
Almost no manual maintenance needed
Generated changelogs include information and links about which commits relate to which features/bugfixes/breaking changes etc.

Commit Message Convention

As the changelog generation is based on a repository's commit, it's crucial that a repository's commits are all well formatted an follow a particular convention to make the system work. There are no restrictions in what the conventions look like as long as they can be parsed to extract the needed information.

The standard convention is the one that is most widely used and probably the best one to go with as there's no additional work needed to make the tooling learn a custom convention.

The convention is pretty straight forward. Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

The header is mandatory and the scope of the header is optional. The footer should contain a closing reference to an issue if any.

Example:

docs(changelog): update changelog to beta.5

fix(release): need to depend on latest rxjs

Some message that gives more details about the change.

Type

Types can differ from project to project as needed, but generally every project could make use of the following types:

docs: Documentation only changes
feat: A new feature
fix: A bug fix
refactor: A code change that neither fixes a bug nor adds a feature
test: Adding missing tests or correcting existing tests
chore: For changes that are neither fixes, features, refactors etc. and unlikely to be noticed by the consumer of APIs

Other types might be perf, styles, build, ci etc. For more custom types, take a look at MachineLabs guidelines.

Scope

Scope really depends on the project as well. In a mono repository, it could be the name of the npm package affected (as perceived by the person reading the changelog generated from commit messages. For inspiration, again, take a look at the linked MachineLabs guidelines.

Footer

The footer is a great place to put comments about which issues are being fixed or closed by the commit. Another information that should go in there are breaking changes, in case the commit in question introduces any. Those can be nicely documented with before and after blocks.

Those breaking changes will show up nicely in the generated changelog as well, making it very easy for developers and consumers of Aragon's API to follow what needs to be done to upgrade their code base.

sohkai commented 6 years ago

❤️ ❤️ ❤️ this. Using standard-version would be awesome, and I'd be inclined to keep the types and scopes fairly loosely defined at this point so that we can easily come to a base standard for all the repos (and evolve them separately as needed).

0x-r4bbit commented 6 years ago

and I'd be inclined to keep the types and scopes fairly loosely defined at this point so that we can easily come to a base standard for all the repos

Totally. The types listed in the AGP are pretty much the most common denominator across any projects.

Scopes can definitely stay lose and change over time. It probably makes sense though, find an easy rule one can stick to (in the dedicated project) so changelogs stay consistent. Anyways, no need to bikeshed on those yet :)

Types are more important they are the barebone of the resulting changelog.

sohkai commented 6 years ago

:+1: Awesome. The only bikeshedding I'll do is requesting chore be added to the list of types 😄. I've used it commonly as a catch-all or project-management related type.

0x-r4bbit commented 6 years ago

The only bikeshedding I'll do is requesting chore be added to the list of types

Ah, good catch. That one's supposed to be on that list. Let me update real quick.

sohkai commented 5 years ago

Something I just came across that could be interesting to set up is commitlint.

aragon / governance