Topic on Talk:Gerrit/Commit message guidelines

Done via this edit by Timo.

One of the key things I think these guidelines miss is the need for titles to uniquely identify what is changing, distinct from other potential commits.

foo: Fix function documentation

… is pretty unhelpful, whereas:

foo: Document function's return types with '@return'

foo: Update documentation to use '@chainable' over '@return self'

foo#bar: Remove `@chainable claim`, this method might return null

… all give much more information (and yet could all be represented by the first title, as I've seen it happen).

Maybe after "Keep in mind that this will be in the repository forever." we could add "Ensure your title briefly but uniquely explains what you have changed." or similar?

(My casual term for this requirement is commit message "passing the Timo test".)

Thanks for added this meanwhile with diff 4905068 in 2021. I apparently copyedited that a few months later. Not remembering either edit, I also added an example just now upon reading this old thread!

Your subject line should be short, clearly state what your commit is changing.It should not be possible to use the same subject line for two commits that do different things. Consider "Fix FooBar docs to use @chainable" instead of "Fix a function doc".