As part of the guidelines for the body we suggest keeping lines with a max of 100 characters. That doesn't work anymore with the new gerrit UI. I suggest we change it to 65-70 max (unless we can change the width of that box)
Talk:Gerrit/Commit message guidelines
Jump to navigation
Jump to search
The industry standard seems to be 72 characters for the body. Perhaps Gerrit is expecting that.
The middle of the current "Good example" of a commit message is currently just nonsense placeholder text. It would be better if this were realistic text, given that this is supposed to help people learn what to write.
I don't understand. The example shows the title with modifier, a bunch of prose, and some references for future work, exactly as required. Inventing "nicer" prose seems very low value?
What should people write in that "bunch of prose" in the middle? How detailed should it be? Should it restate what's in the title? Should it mention which files have changed? The current example answers none of those questions.
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".)
There are no older topics