Does this look familiar?
$ git log --oneline 3c80736 session tests d6dbe2e small update to test 7ce13fb add mockery as a dev dependency 4b61990 update namespace 811b01b use new flash messages implementation 1d2632d remove twig comment 6803457 create test for example form validator d44f7bf fix tabbing 3d8d097 extend the laravel session class a63d0e4 created form validator classes 2cfbfe4 rewrite of flash messages twig handling
It probably does.
As the lines are printed to your terminal you start to feel the vein on the side of your head protrude and you immediately switch back to your browser and open YouTube.
Maybe laughing at children falling over and crashing into glass windows will make me feel better you think to yourself.
Maybe there is more information if I just do this:
$ git log commit 2cfbfe4160731ef4908443bdcad9c0cc1b6a2035 Author: XXXX XXXX <[email protected]> Date: Wed Nov 13 21:16:12 2015 +1100 rewrite of flash messages twig handling commit b97e3970da3505d18236516317035f6bfb65f589 Author: XXXX XXXX <[email protected]> Date: Wed Nov 13 13:06:49 2015 +1100 test bug commit 692e41f07c195a3f9368976dca4e12fc23705e1f Author: XXXX XXXX <[email protected]> Date: Wed Nov 13 13:01:07 2015 +1100 created tests for data class
How about one from a popular open source project?
$ git log --oneline 87c0908 increment version 5f27020 Merge pull request #12709 from vlakoff/class 67abe0a Merge pull request #12713 from mustafaaloko/patch-1 694d164 Code style 56bc6f8 Mention array in mail recipients docstrings e8c0d70 Make use of static::class bdbc2a4 Merge pull request #12613 from sileence/feature/5.2/blade_literals dbcb4ab Merge pull request #12638 from vlakoff/arrays-2
If I'm tending to your pull request, trying to fix a bug or contributing to your open source project I want to be armed with as much information as possible.
Does this look a little better?
$ git log --oneline 577f708 fix(web-messages): Display minutes when concierge call scheduled 6d92a74 fix(web-concierge): Fix automated messages when scheduling call
...and with a bit more information:
$ git log commit 577f7089a7d2d684cf24c13d1f31f4e5d1d539be Author: Jared Mooring <[email protected]> Date: Wed Sep 16 16:23:12 2015 +0100 fix(web-messages): Display minutes when concierge call scheduled The message sent to concierge and client when a call was scheduled was not including the minutes. It now does. [QA]: Has unit tests: Yes Reviewed by: Angel P [TRELLO]: https://trello.com/c/XXX-XXX commit 6d92a749ffaaff7dfa095f8ea68a12061587e12b Author: Jared Mooring <[email protected]> Date: Wed Sep 16 14:02:07 2015 +0100 fix(web-concierge): Fix automated messages when scheduling call This is to fix Commit #0d84995465932b7ab4fe1a88ffaa0f9dfffb3c5a missing this code. For some reason it was lost. The message that is sent to a client once a call has been scheduled has been changed to reflect a much better tone. It includes specifics around the call. A push notification is also sent to the concierge. It's pretty dull though 'X has sent you a message'. [QA]: Has unit tests: Yes Reviewed by: Angel P [TRELLO]: https://trello.com/c/XXX-XXX
It's verbose, I can see the commit has unit tests, I can see it was reviewed, oh and look, I can also go to the ticketing system to see the origin of this issue.
The extra time needed to formulate such a commit is negligent when you consider value.
Make life easier and add a commit template:
<type>(web/api/admin-<component>): <subject> # More detailed explanatory text, if necessary. Wrap it to # about 72 characters. Please make sure to put some # effort in to making this descriptive enough for others # to read and understand. [QA]: Has unit tests: Reviewed by: [YOUR_TICKETING_SYSTEM]: # More information here: # https://pootle.in/your-commit-messages-suck
Adding the template is easy:
$ git config commit.template /location/to/your/template.txt
Filling in the template
- Configure your project to use the above template
- Try to be as verbose as possible. I know that sometimes it's a pain, but please try.
- It's okay to put NIL against items where they do not apply.
subject (first line)
First line cannot be longer than 70 characters, second line is always blank and other lines should be wrapped at 80 characters. The type and
scope should always be lowercase.
feat(new feature for the user)
fix(bug fix for the user)
docs(changes to the documentation)
chore(updating config files etc)
This just helps narrow down the search. Was this change part of the admin section? Was it part of the API?
The component pertains to something specific in your app. Maybe you're working on registration, analytics,user profile, whatever. It's a specific component within your app and product.
Try not to leave the component blank. It can help when skimming through commits.
Here's an example:
fix(api-registration)This is a bugfix for the registration section of the API.
docs(api-account)This is API documentation for the users account.
feat(web-frontpage)This a new feature for the websites frontpage.
fix(web-faqs)- This is a bugfix to the FAQ's on the website.
Includes motivation for the change and contrasts with previous behavior For more info about message body, see:
Has Unit Tests: yes/no.
Your ticketing system
If you're using something like GitHub and a modern ticketing system (Jira / Sprintly for example) you have the advantage of being able to update those tickets directly through your commit message (one they are pushed to remote/origin).
Here's an example of a commit message that updates Jira. It'll update TASK-1882 to be in a new state on the Kanban board, as well as adds a comment:
fix(web-matches): Too many matches being generated The daily matches algorithm was not taking into consideration the offset between existing matches and the total amount of matches to generate when a user had a larger number of friends on network. [QA]: Has unit tests: Yes Reviewed by: Jared Mooring [JIRA]: TASK-1882 #ready-to-test-on-stage #comment This is now ready being built on staging.
Want to see some incredible commit messages? Take a look at the linux kernel: https://github.com/torvalds/linux
In closing, take the extra time to put together a nice commit message.
- Header image courtesy of XKCD - https://xkcd.com/1296/