Mazzocchi Brothers' HandBook

Some conventions on commit messages (and PR titles)

Conventional commits is a standard for writing commit messages.

There are many benefits to adopting conventional commits. But the first thing that an adopter notices is that they simplify the process of writing a good commit message.

All developers are aware how difficult it can be to name things, and writing descriptive yet succinct commits can be even more difficult. By providing a format to follow, conventional commits take away a lot of the thinking work that is required when writing a commit message, and point us in a good direction.

The first thing you need to do before writing a commit message is to ask yourself: “This commit will…“ and then complete the sentence with your commit message.

The result would be like this: add a new feature in my code (attention please: its an example, really!).

After you write a meaningful commit title, you can (it’s not obbligatory) expand with a body. Start to write the body always after a new line.

You don’t need to mention the file where you change the code or other things that can be told you by git; focus only on what your code do.

Following the conventions drawn up by conventionalcommits.org, we derived ours. The commit message should be structured as follows:

<type>[optional scope]: <description>

[optional body]

Types

• Fix: a commit of the type fix patches a bug in your codebase.
• Feat: a commit of the type feat introduces a new feature to the codebase.
• BREAKING CHANGE: a commit that append ! after the type/scope, introduces a breaking API change. A BREAKING CHANGE can be part of commits of any type.
• Types other than Fix: and Feat: are allowed, for example: Build:, Ci:, Docs:, Style:, Refactor:, Test:, and others.

Some examples:

fix: prevent racing of requests
feat(lang): add Polish language
refactor!: drop support for Node 6

The PR title and its merge commit message

When a release is created, GitHub automatically generate the changelog using the pull requests titles.
Although the same rules apply as for commits, it is preferable to omit the type in the title creation. This will make the changelog more suitable for the layman.

GitHub uses a default merge commit message, like: Merge pull request #123 from username/branch-name. Obviously, no one will ever guess what this commit does by reading this kind of title.
To improve the git history readability of the project, also use (copy) the PR title as the merge commit message but adding, at the end, the PR reference.
The result

Add remote and async work sections (PR #5)

will turn the git log in a readable story.

Why Use Conventional Commits

• Automatically determining a semantic version bump (based on the types of commits landed).
• Communicating the nature of changes to teammates, the public, and other stakeholders.
• Triggering build and publish processes.
• Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history.
• Automatically generating CHANGELOGs.

This (can) save us a lot of work (and thinking).