CL descriptions

[Rob Pike]

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]

It might be better to take a look at https://groups.google.com/d/msg/golang-dev/6M4dmZWpFaI/SyU5Sl4zZLYJ too.

- first line has form "component: change"

https://go-review.googlesource.com/c/exp/+/10161, x/exp/rand: blah blah

https://go-review.googlesource.com/c/exp/+/61330, rand: blah blah 

https://go-review.googlesource.com/c/exp/+/61530, exp/rand: blah blah

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]

Thank you for finding that old mail. I'd forgotten I had written it and nearly created another copy.

https://groups.google.com/d/msg/golang-dev/6M4dmZWpFaI/SyU5Sl4zZLYJ 

--
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]

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]

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]

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.