CL descriptions

613 views
Skip to first unread message

Rob Pike

unread,
Sep 12, 2017, 8:24:40 PM9/12/17
to golan...@googlegroups.com
We have a lot of things happening in the repo lately, and new approvers and contributors, and that's great. But the quality of the CL descriptions has been slipping. Please, authors and reviewers, please make sure the CL descriptions are well-written and follow our conventions.

- first line has form "component: change"
- blank line follows
- description after first line is full sentences, in clean grammatical English
- purpose of CL is explained
- mechanism of CL is explained
- for performance-related CLs, benchmark information is presented

and so on.

The CL description is a public document that explains to the future what has been done and why. Please think of it that way, not as a side note to the code. In many ways it is as important as the code, and will often last longer.

-rob

mikioh...@gmail.com

unread,
Sep 12, 2017, 9:50:26 PM9/12/17
to golang-dev
- first line has form "component: change"


I'd personally prefer that the component in the first line doesn't include any repository name, for example, "rand: blah" instead of "x/exp/rand: blah" or "exp/rand: blah".

Rob Pike

unread,
Sep 12, 2017, 9:55:32 PM9/12/17
to Mikio Hara, golang-dev
Thank you for finding that old mail. I'd forgotten I had written it and nearly created another copy.


--
You received this message because you are subscribed to the Google Groups "golang-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Russ Cox

unread,
Sep 12, 2017, 10:14:00 PM9/12/17
to Mikio Hara, golang-dev
For what it's worth, yes the convention in CLs is that the component does not include the name of the repo, so "rand:" not "exp/rand"" or "x/exp/rand:". Otherwise every CL in the repo would begin with the same redundant prefix. 

This is (perhaps confusingly) different from the issue tracker, because we use the golang/go tracker for all subrepos, so in issue titles the repo prefix is necessary (as in "x/exp/rand: Foo is buggy").

Russ

lab...@gmail.com

unread,
Sep 14, 2017, 9:51:10 AM9/14/17
to golang-dev
It would be helpful to have the CL description policy available on the contributions page somewhere.  Then it would be easier to find for newcomers.

Ian Lance Taylor

unread,
Sep 14, 2017, 2:59:07 PM9/14/17
to Lynn Boger, golang-dev
On Thu, Sep 14, 2017 at 6:51 AM, <lab...@gmail.com> wrote:
>
> It would be helpful to have the CL description policy available on the
> contributions page somewhere. Then it would be easier to find for
> newcomers.

It could be more visible, but it's under
https://golang.org/doc/contribute.html#commit_changes .

Ian



> On Tuesday, September 12, 2017 at 7:24:40 PM UTC-5, Rob Pike wrote:
>>
>> We have a lot of things happening in the repo lately, and new approvers
>> and contributors, and that's great. But the quality of the CL descriptions
>> has been slipping. Please, authors and reviewers, please make sure the CL
>> descriptions are well-written and follow our conventions.
>>
>> - first line has form "component: change"
>> - blank line follows
>> - description after first line is full sentences, in clean grammatical
>> English
>> - purpose of CL is explained
>> - mechanism of CL is explained
>> - for performance-related CLs, benchmark information is presented
>>
>> and so on.
>>
>> The CL description is a public document that explains to the future what
>> has been done and why. Please think of it that way, not as a side note to
>> the code. In many ways it is as important as the code, and will often last
>> longer.
>>
>> -rob
>>
> --
> You received this message because you are subscribed to the Google Groups
> "golang-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to golang-dev+...@googlegroups.com.
Reply all
Reply to author
Forward
0 new messages