Skip to content

Commit Guidelines

Jump to bottom Edit New page
mzap edited this page Apr 26, 2015 · 8 revisions

Git commit message guidelines

Goals

  • Allow generating CHANGELOG.md by script
  • Allow ignoring commits by git bisect (Unimportant commits like formatting)
  • Provide clearer information when browsing the history

Generating our changelog

We use three sections in our changelog: New features, bug fixes and breaking changes. This list can be generated via script when doing a new release, along with links to related commits. Of course, the output can be edited before the actual release, but it still gives you a nice skeleton to work with.

List of all subjects (First line in commit messages) since last release:

git log <last_tag> HEAD --pretty=format:%s

New features in this release:

git log <last_release> HEAD --grep feature

Recognizing unimportant commits

These are formatting changes (Adding/removing spaces/empty lines, indentation), missing comments. So when you are looking for some changes, you can safely ignore these commits, since there is no logic change inside them.

When using git bisect, you can ignore these with:

git bisect skip $(git rev-list --grep irrelevant <good_place> HEAD)

Provide more information when browsing the history

The formatting allows a clear view of what a commit is doing, and where it does apply. See these few commits:

Commit_example COMING_SOON

Git hooks

We provide a commit-msg hook that checks the validity of your commit messages. To enable it, just go into the utils directory then type the following command:

./deploy_git_hooks

Format of the commit message

<type>(<scope>): <subject>
<blankline>
<body>
<blankline>
<footer>

The subject line can't be any longer than 50 characters, and the body/footer can't be longer than 72 characters, to ensure maximum readability on any platform.

Subject line

The subject line contains a succint description of the changes.

Allowed <type>

Only the following types are allowed:

  • feat for new features
  • fix for a bug fix
  • docs for documentation-only changes
  • style for changes that do not affect the meaning of the code (white-space, formatting, comments, etc)
  • refactor for a code change that neither fixes a bug or adds a feature
  • perf for a code change that improves performance
  • test when adding a missing test
  • chore Changes to the build process or auxiliary tools and libraries

Allowed <scope>

Scope can specify a single file when documenting, and will otherwise be limited to: core, builder, client.

<subject> Text

  • use imperative, present tense: "change", not "changed" nor "changing"
  • don't capitalize the first letter
  • no dot at the end

Message body

  • Same rules as the <subject>
  • Includes motivation for the change and contrast with previous behaviour

Feel free to check this nice article by tpope for more setup suggestions.

Message footer

Breaking changes

All breaking changes have to be mentioned in footer with the description of the change and justification.

Fictional change example:

BREAKING CHANGE: Re haul of the test procedure to handle specific
cases and new Virtual Machines

Before:
./test specific VM

After:
./test
will automatically handle every VM on the Jenkins build process

Referencing issues / waffle.io integration

We are using waffle.io to keep track of ongoing issues/PR, please specify the issue solved here by its number:

Close #1234

Examples

COMING_SOON

Add a custom footer
Add a custom sidebar
Clone this wiki locally