Links to issues and/or CLs from release notes

[ben...@gmail.com]

Often when I'm reading the release notes (eg: https://golang.org/doc/go1.17), I'd love to see the code changes or discussion that went into the feature. Under the language/tooling sections it might make more sense to link to an issue, as there are probably many CLs for some of the features. But under the library section, there's usually only one CL per "feature paragraph". It would be nice to link to them, particularly in the library changes section.

I notice the CL number and issue links are actually there, but only in HTML comments in the source code. Presumably for doc editors.

My suggestion would be to add [CL 12345] links to the end of every core library paragraph. We could also add [Issue 54321] links to the language/tooling paragraphs where appropriate.

This would make the release notes a bit more interesting and useful, at least for me. Thoughts?

-Ben

[Russ Cox]

On Thu, Sep 23, 2021 at 7:33 PM ben...@gmail.com <ben...@gmail.com> wrote:

Often when I'm reading the release notes (eg: https://golang.org/doc/go1.17), I'd love to see the code changes or discussion that went into the feature. Under the language/tooling sections it might make more sense to link to an issue, as there are probably many CLs for some of the features. But under the library section, there's usually only one CL per "feature paragraph". It would be nice to link to them, particularly in the library changes section.

It's an interesting question, one I've thought about before.

I think that the majority of users aren't and shouldn't be reading the code to learn more,

so the links would be distracting and unhelpful.

Links might also lead to comment threads on those CLs,

which is not really what we want.

I realize that those of us here on this list would appreciate the links,

but we're not the majority target audience for the release notes,

and we have the repo checked out and can easily run something like

    git log1 go1.16..go1.17 src/regexp

I think about: what if I were reading Java release notes?

It might be interesting to see one code change or another, but overall

I would be put off by the idea implicit in the links that I'm supposed to

look there to find out more about the changes.

I shouldn't have to read the code to learn what happened.

If the documentation doesn't stand alone, then we should address that.

Also, even single CL changes often have follow-up CLs adjusting docs

or fixing bugs, and linking to a single CL may well be misleading or confusing.

The CL number comments are used by tooling to make sure we remember

to write something about every CL that's been flagged as worth mentioning

in the release notes, so they will stay, and you're welcome to use them.

But probably we shouldn't make them any more prominent.

Best,

Russ

[ben...@gmail.com]

It's a fair point of view, thanks for the response.

I realize that those of us here on this list would appreciate the links,

but we're not the majority target audience for the release notes,

and we have the repo checked out and can easily run something like

    git log1 go1.16..go1.17 src/regexp

I very rarely contribute to Go development (I have only a small handful of times over the years), so I often don't have a Go checkout ready or up to date. So I'm basically a Go user, though I guess I'm a bit more interested in internals than most (read: easily nerd-sniped).

I think about: what if I were reading Java release notes?

Hey, no swearing on this list! But seriously, I love links like that whatever the project is. I've definitely seem them on various projects.

For what it's worth, Rust's release notes don't: https://blog.rust-lang.org/2021/02/11/Rust-1.50.0.html

Java's don't seem to either (I find that page significantly less readable!): https://www.oracle.com/java/technologies/javase/8u301-relnotes.html

Python does have issue links, like "Contributed by so and so in [bpo-12345]" -- I think that's the main project I'm thinking of: https://docs.python.org/3.10/whatsnew/3.10.html

I guess one option would be to have a button somewhere that says, "Show Code Change Links", but hide them by default.

But overall I think it's fair to prioritize readability and simplicity over "all the features".

-Ben

[Bryan C. Mills]

I do think we could stand to add more links to the release notes, but I agree that specific CLs are probably not ideal.

In most cases, I think we should link to documentation and/or issues instead:

1. For each section describing new or newly-refined functionality, link the documentation for that functionality — either package documentation on pkg.go.dev, or in the relevant reference documentation (golang.org/ref/spec or golang.org/ref/mod or similar). That would not only help users to find more detail about the change, but also serve as a nice reminder for those of us (like me 😅) who sometimes forget to document new command behaviors.

2. For each change made as a result of the proposal process, link the proposal issue and/or proposal discussion. That would help users figure out why things were done a particular way, and may help to reduce issues filed for aspects of the design that were deliberately chosen during the proposal process.

3. For each section describing a significant bug-fix, link the corresponding issue in the issue tracker. That would help users find more details like “how do I know if I am affected?” or “what workarounds are available for users on previous releases?” or “which minor releases contain backports for the fix?” without adding too much noise in the release notes.

--
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.
To view this discussion on the web visit https://groups.google.com/d/msgid/golang-dev/11d862b1-81c1-479c-a49c-d0de9b3ecc79n%40googlegroups.com.