In Git it's possible to set and enforce a good commit template.
Can you recommend (preferably with argumentation) a good commit template / guidelines to enforce in the company?
With Add, Mod(ify), Ref(actoring), Fix, Rem(ove) and Rea(dability) then it's easy to extract logfile.
Add: New function to rule the world.
Mod: Add women factor in Domination.ruleTheWorld().
Ref: Extract empathy stuff to an abstract class.
Fix: RUL-42 or #42 Starvation need to be initialised before Energy to avoid the nullpointer in People.
Rem: freeSpeech is not used anymore.
Rea: Removed old TODO and extra space in header.
If I have more than a line, I sort them with most important first.
We use the following:
[Ticket's Id in JIRA]: [Message: What was done] For example - ABC-123: Added ability to configure presentation per region.
In this case with proper integration you will be able to get changed/deleted/added files in your issue tracker. However, be aware that you should prevent something like ABC-123: Done or ABC-123: Fixed with filters if possible.
There is one simple rule, which is a convention followed by many (if not all) SCMs and by most tools that work with SCMs :
The first line of a commit message is a short summary, while the rest of the message contains the details.
So, most tools display the first line only, and display the whole message on demand.
A typical misuse of a commit message is a bullet list of changes (only the first bullet will be shown). Another misuse is writing a loooong detailed message on a single line.
So, if there is one thing to enforce, I would say it's the maximum length of the first line.
Personally I've never seen a general commit template worth using. The comment should concisely say what the commits are related to e.g. what feature/bug fix or a brief statement of why changes were made.
Information on what was committed should not be included, this can be determined by the scm system. More bug/feature information belongs in where ever bugs and features are tracked.
When updating a bug report after a commit I find it's good to also state the commit revision along with the comments in the bug report. This way you can find your way from the commit comment to bug report, and for each comment on the bug report you can find what was committed, but you do not duplicate information by having it on both the bug report and commit message.
Then when viewing history of revisions for a file, you have nice brief messages describing the history but also know where to look for more details bug reports or task descriptions for more details.
In Git it is possible to enforce nearly anything with Git hooks. Check the examples in .git/hooks for ideas.
As for the message, in a very general case, you want to include enough information about the problem you were solving AND the solution itself to be able to find and identify this commit later. In most cases the problem will be referenced a bug number (with proper integration with your bug tracking system). If you have other systems your process integrates with (like the code review tracking system), include the appropriate bits as well:
Extracted checking foobar range from bar() into foo(min, max) to re-use
in yadda() and blah(). foo() returns true if foobar is in the
specified range and false otherwise.
BUT you wanna keep it simple. Otherwise, people will find a way to cheat the system and produce useless commit messages.
We use a template containing
The first two are omitted most of the time however (occasionally all three) so its not really a big deal.
I generally have the identifier that is in the ticket tracking system I use or a high level overview as the first line. Then I have line item "bullet" points of the specific change in the commit. So I could of something like:
MyVideoGameProject-123 OR Inventory System Improvements
Made inventory GUI drap and drap
Added ability to have multiple bag slots to expand inventory capacity
This is the cleanest commit format I like. It is direct and to the point. Another reason I do it this way is that if I want to create a change log, I could just take all the commit messages and parse it into a change log very easily.
[ticketId][ABC][topicId][WIP] Message, where:
[#452567][add][menu_item] new item - guestbook
[#452363][fix][banner_top][WIP] 1024x300 can be used now
[#452363][fix][banner_top] 500x200 can be used now
[#452713][rem][page] left middle ad