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