Release note process question

documentation
1

Hi,

I learned via an LWN comment that Rust now does release notes via issues and then the team writes them if there's no response. We used to do this for VTK and the no-response rate was through the roof. The number of "I fixed a typo"-level responses only further decreased the effectiveness of this method for gathering release notes.

What has worked much more effectively is to just do it as part of the original patch submission in the first place. The obvious route (just edit some changelog file directly) leads to endless conflicts as submissions try to add to the end of the file (or section). Instead, we found that instead, a file per noteworthy submission in a directory works better. No conflicts, the ability to edit them as features evolve over the release process, reverts remove the notes, and backporting brings them along.

Basically, there's a directory with some template anchor file that gives an idea of what a release note looks like. There can be metadata fields, section headers, guidelines on what is worth a release note, etc. Contributors then copy the file into a sibling that is named after the feature in question and edit there. It can then be reviewed as part of the normal review process and updated in followup patches as needed.

Thoughts? Is this the right place to bring this up? Perhaps Zulip or Github is better?

Thanks,

--Ben

3 Likes
2

Zulip #t-release is probably a better place for discussion.

The process is very new, but this fallback is essentially the status quo we had before. Usually that means we would start with the PR subject and try to reword that for a wider audience, if needed.

"I fixed a typo" PRs should never get a relnotes label for our attention in the first place.

3

I agree. Our process was to git log and filter for each author and email the authorship email address asking to summarize their commits which is why these even got any response on our side.

Thanks, I'll head there.