doc: eliminate commit-message skew between Contribution Guide and wiki

[bcmills]

After @rasky's updates, https://tip.golang.org/doc/contribute.html#commit_messages has a nice, clear guide to Go commit messages. https://github.com/golang/go/wiki/CommitMessage has a very similar guide.

Unfortunately, they have a bit of skew: for example, the wiki mentions a 76-column limit, whereas contribute.html does not.

We should eliminate that skew: either both documents should list the full details, or one should provide a more concise summary and link to the other for details.

[nodo]

Hey @bcmills, I would like to start contributing and I would be interested in picking up this issue is that OK for you?

[bcmills]

That would be great, but please coordinate with @rasky on the changes.

[nodo]

Thanks @bcmills.

I would have only one place with full details and link it where needed. Which one you think it's more important for this docs: the wiki or golang.org?

/cc @rasky

[rasky]

That's a good question :) I'm not the right person to cast the call, I don't have enough insights on how the wiki was born and evolved. In fact, the whole contribute.html could be on the wiki, in principle (or vice-versa, the wiki could become html pages of the website). One thing I don't like of the website is that it follows the Go release cycle. Waiting 6 months to push an updated to a webpage is not reasonable: I'm not sure if this is something that could be fixed or not.

Maybe we should ask @bradfitz or @spf13 if they've got some suggestions on the matter. If we're not ready to cast a call on how to solve the wiki vs html conflict, I think we could go conservative and just align the two for now. That would be an immediately actionable CL.

[bradfitz]

I've updated the wiki with a link to the other page and adjusted some of the wording around 76 characters to say why we say that. (The contributing page had that part removed because Rob was against, but the reality is that many web-based git commit viewing tools assume wrapped commit messages, so we're just acknowledging that.)

[bcmills]

I don't think that actually fixes the skew: contribute.html (which is arguably much more discoverable than the wiki) is still missing information relative to the wiki, and still doesn't link to it. A contributor who starts at https://golang.org will still end up with an incorrectly-formatted commit message.

If wrapping to 76 columns is not a real requirement, then we shouldn't enforce it in code review and shouldn't refer to it in the wiki. On the other hand, if it is a real requirement, it should be easier to discover from the obvious starting point (https://golang.org/project/).

[bcmills]

@robpike, do you have a suggestion for how we should resolve this?

[bradfitz]

If wrapping to 76 columns is not a real requirement,

As far as I'm concerned, it is a requirement.

I know Rob dislikes punchcards and line limits, but I will continue to tell people to format their commit messages with word wrapping so they look nice in popular tools that assume we still live in a world of punchcards.

I'll let @bcmills own this bug's resolution, but if somebody deletes that text from the wiki, I would be forced to waste time in code reviews repeating myself, reiterating the then-deleted text, at which point I'd probably create a new uneditable URL saying the same thing.

[Windsooon]

When the first time I contributed to golang, I forgot to add a blank line after "Fixed XXX" as well as other mistakes. After that, I made a PR (commit 67653c4cd04edde8df483d06fb85a89843d1f306 (HEAD -> fix-contribute, tag: fix-contribute.mailed)) for it. So I agreed we should copy this from the wiki.

Notably, for the subject (the first line of description):

the name of the package affected by the change goes before the colon
the part after the colon uses the verb tense + phrase that completes the blank in, "This change modifies Go to ___________"
the verb after the colon is lowercase
there is no trailing period
it should be kept as short as possible (many git viewing tools prefer under ~76 characters, though Go isn't super strict about this).