Talk:Gerrit/Commit message guidelines

Jump to navigation Jump to search

About this board

Previous discussion was archived at Talk:Gerrit/Commit message guidelines/Archive 1 on 22 March 2019.

New gerrit UI does not fit 100 characters in the commit message box

2
DMaza (WMF) (talkcontribs)

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)

MusikAnimal (WMF) (talkcontribs)

The industry standard seems to be 72 characters for the body. Perhaps Gerrit is expecting that.

Reply to "New gerrit UI does not fit 100 characters in the commit message box"

Please improve "Good example"

3
Yaron Koren (talkcontribs)

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.

Jdforrester (WMF) (talkcontribs)

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?

Yaron Koren (talkcontribs)

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.

Reply to "Please improve "Good example""

Add bullet about title uniqueness?

1
Jdforrester (WMF) (talkcontribs)

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".)

Reply to "Add bullet about title uniqueness?"
There are no older topics