Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
bcmills opened this issue May 9, 2018 · 9 comments
Open

Comments

@bcmills
Copy link
Contributor

bcmills commented May 9, 2018

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.

@bcmills bcmills added this to the Unreleased milestone May 9, 2018
@bcmills bcmills changed the title doc: eliminate skew between Contribution Guide and wiki doc: eliminate commit-message skew between Contribution Guide and wiki May 9, 2018
@nodo
Copy link
Contributor

nodo commented May 14, 2018

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

@bcmills
Copy link
Contributor Author

bcmills commented May 14, 2018

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

@nodo
Copy link
Contributor

nodo commented May 15, 2018

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
Copy link
Member

rasky commented May 15, 2018

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
Copy link
Contributor

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
Copy link
Contributor Author

bcmills commented May 16, 2018

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 bcmills reopened this May 16, 2018
@bcmills
Copy link
Contributor Author

bcmills commented May 16, 2018

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

@bradfitz
Copy link
Contributor

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
Copy link

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

6 participants