Commit guidelines
This document was written as an overview of how an optimal commit should be written. But in the end it is still your decision, no Pull Request should be stuck in a review phase because its commits differ from the practices described below.
But if you are unsure of how to write them, this should give you a good starting point for great collaboration.
As a general guideline, you can follow the idea that a single commit should enclose a single problem/feature that has been fixed/added.
This way of organizing your changes to the codebase makes is easy for reviewers and people who try to understand the history of a project to determine what has been happening in the project.
Here a both a good and a bad example of commit message.
Bad:
fixes bug
Good:
Fixes bug where database gets deleted on POST request
Conventional commits
Commit messages should follow the following structure.
- Start with a type: fix or feat for new features.
- A scope in brackets. Short description in a single word of the changed parts.
- Description of the changes (see above paragraph).
- If you have a Ticket, add it at the end of the commit message.
With this set of rules, reading the git log is very easy for humans.
Example commit messages
- fix(readme): update haproxy config
- feat(image): add image import WD-324
Breaking up large tickets
If your feature/ticket includes multiple things that you have to complete in order to submit a pull request, these should all be seperate commit messages, according to the general guideline above. This will make it easy for the reviewer to understand what exactly has happened.
But make sure that this is a something that is done throughout your project. If another workflow is used, such as squashing all your commits together before you merge your branch into master, this is not necessary. Just make sure that your commit message for the squash commit includes a detailed message of the changes. A great tool for this case is a multiline commit message.
For adding a new page in an example Project, this could look like the following for separate commits:
Add the Person model
Configure the Views to use the new Person Model
Use the Data from the Views in the index template
and like this for a squashed multine commit:
Add Persons to the app
- Add the Person model
- Configure the Views to use the new Person Model
- Use the Data from the Views in the index template
For more information about how to write good commit messages you can check out this great article by Chris Beams
Last updated 8 months ago.