Proposal: Introducing commit message conventions for the Embark project


#1

Goals

This proposal’s goal is to support a possible changelog strategy for Embark by using automated tooling that relies on commit message conventions.

Therefore:

  • finding consensus on using commit message conventions
  • ideally decision making for a convention

are needed.

Description

In order to get transparent changelogs for releases Embark could rely on tooling to automatically generate changelogs from the project commit histories. There are basically two parts to make this work:

  1. 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.
  2. 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 Embark’s API to follow what needs to be done to upgrade their code base.


#2

I really like the idea, that will be really useful and as a benefit we can even generate changelog almost for free.

I also would like to add the automation, this tool for example could help us on make sure we are following conventions:

It is not difficult to add and will ensure we are doing commits following the playbook


#3

Super happy to see you in this thread @anthony!

Yes, we would automate as much of this as we can. AFAIK, at the moment the entire release flow is manual (correct me if I’m wrong here @michaelb). But the good thing is that all of the tooling to make this a great experience already exists.

We really just need to make use of them. I would’ve already moved ahead and implemented this but I haven’t seen a green light from the entire team yet.

Would be great if we could push this forward, now that devcon is over and we can focus on such things as well.