Re: [platform-dev] Commit messages

[Andrey Loskutov <loskutov@xxxxxx>]

Thanks Wim to bringing this up.

We have [1] for commit message conventions, but it is unfortunately not really followed in the platform. The only thing is used is the link the bug number in commit title - this is good, but that is too less for a good commit message.

My main point is: all non trivial commits should have a concise explanation of what was changed, why and how.

So whenever someone adds a new algorithm one should explain what that new thing does, which assumptions were made and how that improves the current state. If this is a bug fix, one should explain why the bug can happen, which preconditions lead to broken behavior and how the change addressed the problem.

Why is this important?

Typically one has a broken or incomplete functionality and want fix or enhance that in some way.  The non trivial code is typically clear only after a longer studying and debugging it, so a good commit message is a big help for the reviewers of the change and saves a lot of time (and sometimes even the lack of time makes the review not possible).

Besides this obvious benefit during the review, a more important reason to write good commit messages is the maintenance of the code. There is usually no documentation on the code itself, not much more in a wiki and no concept documents somewhere else. So beside code comments, the only documentation we have is the git history, and that one could be a big help for everyone who tries to maintain the code.

But we have link to the bug and have comments on the gerrit, isn't that enough?

One should clearly separate bug comments, review comments and finally commit messages.

Bug comments are helping to find a solution. Bugs in bug tracker have sometimes few dozens comments and the purpose is to identify and agree on an idea for a fix or for a feature. It is not unusual to have bugs with more than 50 comments, and the "right" one may be somewhere in the middle of the discussion. Therefore a bug is not so convenient to be used as an documentation for the change, because before one can find the right comment, one need to read through all the comments - and that costs time.

Review comments help to refine the choosen solution and to polish the code change. Of course many times longer discussion of the solution can happen in the review, but I would then move back to the bug in such cases. Similar to bug tracker, reviews are not very convenient to document anything - for same reason. We sometimes have reviews with big number of change sets and comments about the code style, build errors, failing tests or other issues etc - all things that are important for the review process but irrelevant for the change documentation. 

And finally we have commit message. Together with the code diff itself this descibes best the intention of the committer, the *final* word on the change reason and the ultimate documentation for the future maintener of this code.

So please, next time you write a commit message, try to imagine, you will see this code in five years again - and which documents you would need if you would like to change it again. May be that would be only the commit message in git history.

[1] https://wiki.eclipse.org/Platform/How_to_Contribute#Commit_Message_Conventions

Am 24. Oktober 2020 14:11:57 MESZ schrieb Wim Jongman <wim.jongman@xxxxxxxxx>:
>Hello,
>
>Andrey recently pointed out on a couple of commits that commit messages
>could be better. I agree with that.
>
>Can we discuss this?
>
>Cheers,
>
>Wim
>
>A list of recent commits is here:
>https://git.eclipse.org/c/platform/eclipse.platform.ui.git/log/

--
Kind regards,
Andrey Loskutov

https://www.eclipse.org/user/aloskutov
Спасение утопающих - дело рук самих утопающих