-
Notifications
You must be signed in to change notification settings - Fork 94
Commit Guidelines
- Allow generating CHANGELOG.md by script
- Allow ignoring commits by
git bisect
(Unimportant commits like formatting) - Provide clearer information when browsing the history
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
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)
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
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
<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.
The subject line contains a succint description of the changes. You may read it as:
"What_I_do(Where I do it): How I do it"
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
Scope can specify a single file when documenting, and will otherwise be limited to: core, builder, client except for docs(the scope represents the edited file) and chore(scope represents the tool that is updated/added).
- use imperative, present tense: "change", not "changed" nor "changing"
- don't capitalize the first letter
- no dot at the end
- Same rules as the <subject>
- Includes motivation for the change and contrast with previous behaviour
- Links to the solved issue using
Fix #X
if need be
Feel free to check this nice article by tpope for more setup suggestions.
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
We are using waffle.io to keep track of ongoing issues/PR, please specify the issue solved here by its number:
Close #1234
COMING_SOON