1

I am starting a new repository from scratch and I want to ensure I start off correctly. I am talking over from a previous developer who used github terribly and I want to fix it before I continue developing on to of their code.

I have done a lot of reading on github and I will be putting the repository together tomorrow. I was hoping to get your opinions on the format of the git commit message I will be using and if I am doing anything incorrect (format, too detailed etc) All my commits will be following the same format so I want to get it right.

Here's and example of one of my commit messages, thanks in advance.

"Add WIFI reconnect

Added code to force WIFI module to save and reboot if it has been over 45 seconds since a packet has been sent successfully.

This was added to fix an issue where the WIFI module lost connection to it’s network. Once disconnected it would only try to reconnect a limited number of times.

Now if the WIFI module disconnects or data has not been sent correctly for 45 seconds, a reboot will be forced and the module will try to connect and transmit on wakeup."

Improve this question
5
  • 1
    I will just give my 2 cents. You should try to write short and concise commit messages. If you have such lengthy commit messages I would probably create issues in the issue system instead and simply refer to the issue from the commit message. Like "Fixes #346: Adds WIFI reconnect, now automatically attempts a reconnect if over 45 seconds since last packet". Then a more details description of the issue and proposed and implemented fix would be on the issue, and not in the commit log. You should try to describe what you did, and leave the why to the issue.
    – Lasse V. Karlsen
    Commented Oct 13, 2016 at 13:48
  • 4
    However, I am also going to vote to close this question as "Primarily opinion-based", as there is no definitive answer here, just opinions. That's also why I wrote the above comment as a comment, and not as an answer.
    – Lasse V. Karlsen
    Commented Oct 13, 2016 at 13:49
  • Hi Lasse, thank you for your reply. I will take your advice and try to shorten my messages. Unfortunately there is no issue tracking system in place. It is a small company and the old developer left before I started. I am the only developer now so I guess I will have to start using one. What would you think of a short commit and adding the detail in the history section of my source code?
    – user1649972
    Commented Oct 13, 2016 at 14:05
  • 1
    I just assumed that since you used the tag [github] that you're on github with your code, and then you already have an issue tracker. I would definitely not write commit-like messages inside your source code. If you don't have an issue tracker in place, and cannot use an issue tracker (for whatever reason), I would write up something between what I proposed and what you proposed. I still think you should have a todo-list somewhere with what you need to fix, and could refer to that, but in total absence of that, write whatever makes sense for you.
    – Lasse V. Karlsen
    Commented Oct 13, 2016 at 14:05
  • 1
    Hi Lasse, thank you so much for the help, I'm new to github, only picked it up this week. I just had a look at the issues section on github and I will 100% do my research and start using it from now. Thanks again
    – user1649972
    Commented Oct 13, 2016 at 14:09

3 Answers 3

Reset to default
1

Writing a good commit message is important, and it's fantastic you're putting so much thought into it. In general, the rule of thumb is to write in present tense and to write short, descriptive messages.

Maybe more importantly, commits should hold small and logical units of work. It appears in your example that the code encompassed in that commit could be a lot of code, maybe too much. Your example looks like a great merge commit, or merge/squash commit message.

So, smaller commits, present tense short messages, only use the extended description when necessary.

Improve this answer
4
  • Hi Briana, thank you for the reply. I was actually quite a small amount of code. One new function, a few variables and just changing some code flow. That's the reason I used this example, it was a very small modification with a large explanation. I am ensuring I make a lot of regular commits in case I have issues and need to revert etc. Can I ask how you would write it with the above information? Do you think I would I be better off with very small commit messages and keep a more detailed history in my source codes main file?
    – user1649972
    Commented Oct 13, 2016 at 13:59
  • 1
    In general, small commit messages work well. If this is a legacy project with a lot of context, it may be best to keep it in more easily read documentation than putting it in lots of commits, then maybe linking to that documentation within commits.
    – Briana Swift
    Commented Oct 13, 2016 at 15:26
  • Hi Briana, not sure if you will still see updates on this still but I was wondering if I could get your opinion on merge messages. Currently I am branching, committing maybe 20 times on that branch and then merging. Each commit has a good title and quick body description, usually attached to an issue. I was wondering if you had an opinion of how I should use the merge message. At the moment I am thinking of using it to list all of the commits that were in the merge as I could not possibly summarize my commit descriptions. Would a list of 20 commit titles be crazy to add to a merge message?
    – user1649972
    Commented Oct 17, 2016 at 16:02
  • 1
    @user1649972 I think it would probably be better to try your best to fit a general merge description, like "merging branch for bugfix in navigation" or "merging release 1.3 branch" instead of listing commits, but that's entirely opinion.
    – Briana Swift
    Commented Oct 18, 2016 at 13:59
1

My usual practice is to have minimal yet clear commit messages, to make history short. Just imagine looking over the git log of a file that has similar commit messages to yours, it's like reading the book.

On the other hand, some problem fixes needs more elaboration and explanations, that's where issue tracking comes in. You can mention the issue number in commit message for a reference. Github even allows to automatically close the issue when you provide the magic phrase in commit message and push the change.

Of course, every developer has it's own style, and this question is absolutely opinion-based.

Improve this answer
1
  • Hi Andrejs, thank you for the reply. I will be looking into the github issues tracker before I start the repository from scratch so that I can use Github correctly.
    – user1649972
    Commented Oct 13, 2016 at 14:12
0

So I have decided to answer my own post using the information that all you guys have given me in your answers and replies. I am doing this because this is more of an opinion based question that can't really be answered and I would like to close it off.

I have decided that I will be adding much shorter commit messages and using the issues tracker on github (which I just discovered, thanks to you all) to hold the more detailed information. My new format for commit messages along with my issues opening and closing comments are below in case it might help someone else. Thanks again guys, I really appreciate all the advise.

Issue comment:

WIFI module loses connection to its network. Once disconnected it will try to reconnect a limited number of times before timing out.

Issue close comment:

Added code to force WIFI module to save and reboot if it has been over 45 seconds since a packet has been sent successfully. The save and reboot will occur regardless of network connection. On wakup the module will attempt to connect and transmit.

Commit message:

Add WIFI reconnect

Fix issue #1. Adds WIFI Reconnect. Now automatically attempts a reconnect if over 45 seconds since last successful packet.

Improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.