Commit messages are not consistent and hard to read

[Anth0rx]

As a friend of consistency I think we should settle on a specific commit message format.
Before explaining much I would like to refer to the following page:
https://chris.beams.io/posts/git-commit/

What are your thoughts on this?

[Taose]

My thoughts, but no doubt others will disagree with me.

Is that the "criticisms" levelled by Chris are nothing short of elitism. They fail to establish to get to the root of the problem and instead believe that comments should be tweets, no doubt he wants them to have #tags.

Short comments are no better than long comments. It is important that a comment is informative, it states why. I will point out that there is actually some guidance in the Wiki as to commit comments. However they are simply guidance.

Some times a commit covers more than what fifty...or one hundred and forty eight characters can contain and as such needs to be verbose. Chris' advice is great if you're telling none-coders what you've done, or its your own project and you just need reminders but for open source or any project that plans to be picked up again like Vegastrike needs verbose comments. They need to cover what has been changed, why it has been changed and which method was chosen and why that method was chosen.

Ultimately, the order of the words is down to the individual, but I do not think it is wise to impose restrictions on number of words, whether something has a capital letter or whether it has a full stop and when to make a new line.

One thing I did find useful, was the "complete x" section, although I feel that words such as "bug" without telling anyone what the bug is, ruins the entire point.

[Anth0rx]

Thank you for your comprehensive response. In my opinion the subject should be as precise as it can be. Further "hows" can be added in the body of the commit. Also this results in more atomic and concise commits, since the contributor needs to make commits in a more modular/atomic manner.

They fail to establish to get to the root of the problem and instead believe that comments should be tweets, no doubt he wants them to have #tags.

What do you mean by this? I think he points out the problems of inconsistent commits quite well. In my experience making atomic commits results in a more structured workflow. So it helped me a lot.

[Taose]

The root of the problem is typically that comments are usually...

"Commit to get rid of bug" without saying what bug. The above author doesn't focus on consistency, he focuses on length and very specific items such as whether or not to include a full stop.

But we do have something.

https://github.com/Taose/Vegastrike-taose/wiki/Coding---Commenting-and-Documenting

[Anth0rx]

The "Commit Messages" section of the aforementioned documentation page is quite sparse. And the one example gives is just a one-liner. Since GitHub has a 72 characters subject line limit such a one-liner looks quite ugly in the log. What I meant was defining what should be in the Subject line and what should be in the body part of the commit message.

I would recommend something like this:

Title

[type][short path to file][stage reached]
Description of the problem;
What you did to solve it;
Optional Contact details

And for the concrete example given in the documentation something like this:

Narrowing from Double to Float

[Warning][src/main.cpp][make]
Warning displayed in GCC on line 92 whereby a function elsewhere was expecting a float but was being give a double.
Decided that the function parameter needed to be changed to accept the increase in memory, so change the parameter from float to double as the variable needed more precision.

In my opinion this would look more concise and polished. What do you think?

[Taose]

I think, I'm not going to make a final decision on this, I have concerns and believe that other stuff could be represented better in other ways however I have no objections to your use of this style provided that you use it consistently.

It is my view that people should actually check the commit in full and that they would be more interested in knowing the file name that was changed first. So have at and we'll see how it develops what people like and don't like.