-
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:%sNew features in this release:
git log <last_release> HEAD --grep featureThese 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:
-
featfor new features -
fixfor a bug fix -
docsfor documentation-only changes -
stylefor changes that do not affect the meaning of the code (white-space, formatting, comments, etc) -
refactorfor a code change that neither fixes a bug or adds a feature -
perffor a code change that improves performance -
testwhen adding a missing test -
choreChanges 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 #Xif 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