Suggestions: Good format for short/commit messages for User Story and Sub tasks

Question

I would like your opinion regarding a good style/format for short messages when committing into a repository (GIT or SVN).

Considering we are using a feature branch development approach, with one branch per feature assign to only one developer at any time and I am interested to commit often in the repository.

Let's imagine I have a "User Story/Case" to code, example:

• User Story 125: Adding basic style to widget Image

"User Story" is divided in sub-tasks, these are particolarly technical, example:

• 01 Change CSS image tag.
• 02 Update decorator.
• 03 Update widget instance in Panel.

....

At the moment we use this format/style when committing:

STATUS - USER CASE - TASK

Example:

PROGRESS : User Story 125: Adding basic style to widget Image - 01 Change CSS image tag

with meaning:

• The first task for a specific User Story has been competed, but the User Story is not completed yet.

This is repeated for each completed sub-task.

When all sub-tasks are completed I use this format:

STATUS - USER CASE

Example:

• DONE : User Story 125: Adding basic style to widget Image

Same approach is used for Bugs.

When the branch is marge to main line we use:

DONE - USER CASE

Without mentioning the sub-tasks.

I would like have your opinion on:

• Do you see any CONS for this approach?
• How would you change/improve it accordingly with some good practice?
• For GIT, does make sense using "staging"on developer branch when committing sub-tasks?

Thanks in advance for your time on this.

Answer 1

Many tools use the first sentence or first line of the commit message as a summary, and the format you've chosen is very wordy. These tools often have a limited amount of space, and brevity (along with clarity) in general is good for commit messages.

For example, with a long prefix and only 32 characters to show the summary, progress on three tasks that all ask to add something might look like this:

• PROGRESS : User Story 125: Addin ...
• PROGRESS : User Story 125: Addin ...
• PROGRESS : User Story 125: Addin ...

Compare that to a more concise form that uses an abbreviation for the story, and omits "PROGRESS : ":

• #125: Adding basic style to widg
• #125: Adding tests for new style
• #125: Adding fix for documentati

Admittedly that's a somewhat contrived example. The point being that with your format, the unique part of your message -- the interesting part -- is far to the right of the message.

Just like with code, you should optimize for clarity. Unless you really, really need "PROGRESS" and "User Story", I recommend omitting them in favor of something more concise. "PROGRESS" in particular seems absolutely useless -- aren't all changes progress? You could still use "DONE" for the final step, and assume if you don't have "DONE" then it must be "PROGRESS".

For extra reading, here are some good articles:

• https://stackoverflow.com/questions/2290016/git-commit-messages-50-72-formatting
• https://git-scm.com/book/ch5-2.html#Commit-Guidelines
• http://chris.beams.io/posts/git-commit/
• https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message