Sig-release: Separate Release Notes website

[jeefy]

There should be a better way to consume a change-log / release notes than a markdown file. I made a POC that shows one possible option, allowing users to filter based on SIGs, areas, and versions. It consumes the JSON output from the current golang release-notes tool in k/release (Thanks @marpaia) and does not require a database backing it.

It is definitely not anywhere near "done", but it does demonstrate that we could do better with release notes.

Other features discussed or thought up were:

• I am on 1.12.3 and want to upgrade to 1.14.0 -- What's changed?
• Linking changelog entries to KEPs to show full enhancement lifecycle
• Search box
• Toggling filter logic (currently defaults to OR)
• Allow linking to Docs from relnotes and vice-versa

If this gets a lot of momentum I'll pull it out of my personal repo and get it in an official repo (under k-sigs?) sooner rather than later. I welcome any and all ideas and feedback.

[spiffxp]

I would be in favor of a kubernetes-sigs/relnotes repo for this (or something with a more fun inscrutable name that makes it impossible to understand what it does because come on this is kubernetes)

[BenTheElder]

kubernetes-sigs/papyros :scroll: :heavy_check_mark:

(more seriously huge +1 on this project and also a kubernetes-sigs repo!)

[justaugustus]

Echoing my sentiments from the SIG Release call: THIS IS REALLY AWESOME!
I think that we should try to keep the tooling in one place, so I'd suggest moving this into a directory in k/release as part of the Release Engineering subproject. Additionally, perhaps we need some workflow to periodically dump the JSON output from the relnotes tool somewhere.

Happy to have you move forward on this from a Chair perspective. Adding the other SIG Release Chairs to comment: @calebamiles @tpepper

/assign @jeefy
/priority important-soon
/milestone v1.15
/kind feature

[justaugustus]

Tagging @castrojo as he may have thoughts on the Contributor Site additions (ref: https://github.com/kubernetes/community/issues/1819).

[jeefy]

Some thoughts re: Periodic JSON dumps (automate all the things)

Currently, aside from a changelog, we put the following in our Release Notes:
Security Content, Urgent Upgrade Notes, Known Issues, Deprecations, ~Major Themes~, New Features, External Dependencies

Besides Urgent Upgrade Notes, everything references a PR or an Issue.
The Known Issues references GitHub issues that also have a v1.x milestone. -- That should be all-encompassing
Security Content has the area/security label -- I feel like any "security content" in release notes should list this.
New Features have the area/feature label -- But there's no way to tell what's "new" from not.

So what's left is handling Urgent Upgrade Notes and External Dependencies -- I feel like _both_ of these could be handled with additional labels within PRs.
If we do that, we could pretty easily generate the whole of the release notes with minimal intervention, and after that we just have to spot check what's generated and massage it mildly

I also recognize a lot of this is "easier said", and won't be part of 1.14, but I'm thinking ahead. This weekend I'll look to PR the app into k/release under something like "relnotes.k8s.io" or "papyros" (thanks for the name @BenTheElder)

[jeefy]

@justaugustus Thinking on it, I'm all for keeping tooling in one place, but this is something that would be iterated on and (auto-)published onto a website. Would it make sense having that kind of build pipeline within k/release?

We also still need to work out hosting for it. Any input on where to go to figure that one out would be welcome. I'm gonna try to get some work done on this over the weekend so it's in a happy place to move whenever/wherever we want it.

[marpaia]

With regards to hosting, I've had good experiences using Netlify's free tier for various open source project websites.

[jeefy]

+100 to Netlify

Speaking of: https://k8s-relnotes.netlify.com/

That's building out of my repo for now.

[spiffxp]

Personally dumping everything into k/release is not the direction I would want things to go. Keeping this tool in its own repo discourages strong coupling to other parts of the release "toolchain". It's not clear to me why we would want to encourage the opposite (if there are explicit goals to do so, I would like to see a plan). I would if anything favor extracting the cmd/relnotes tool out of k/release, unless it is strongly coupled.

But! I am not a subproject owner, merely someone who advocated for its creation, and is advocating for community ownership and use of this tool.

[tpepper]

This is nice in how it lets a viewer dynamically pick and choose their areas of interest.

I still think we have a gap in non-automatable task of curating the quarterly release's human readable summaries. We trend towards things that are variations on 'git log' and that's not meant for normal humans, imho. But this is orthogonal and is partly covered in highlights by the work the comm's team does around release time.

That mostly then leaves a question of where we put this.

I feel like k/release might be something that over time drifts out of existence and into other repos. So I too could agree to a relnote specific repo, but it needs well documented in the release team handbooks for branch and patch management where there's already a need to keep content of multiple repo's in just the right checkout state to do things.

[jeefy]

I volunteer as tribute re: updating documentation, and I'm aiming to shadow release notes for a second cycle so I can see this through to completion.

[onyiny-ang]

As others have stated, this is a really promising tool that I think will be very much appreciated by the kube community. Great work and big shout out to @jeefy :tada:

I also hope to be involved with the 1.15 rel-notes team (tentative lead) and hope we can find a way to address some of @tpepper's (and others') concerns about the gap in non-automatable note curation. I think with @jeefy's tool in place (which place exactly is unclear but I think a k-sigs/relnotes repo might make sense), there's potential to direct the current dump of relnotes to the UI so users that want to dig deeper into specific bugs/issues or see a particular SIG's activity for the release milestone will have an easy access point. That would open up the release notes team to focus on ensuring the Major Themes, Known Issues, Action Required and any other notable sections are concise, readable and shorter than 22 pages :sweat_smile:

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[nikhita]

Can this be closed? We have https://relnotes.k8s.io/ now! :tada:

[onyiny-ang]

@nikhita, yes I think it's safe to close it since the relnotes site is now up :tada: :smile: We will be looking for feedback starting from this release but given that there is now a kubernetes-sigs/release-notes repo, that would be the most appropriate location for issues/feedback on the tool.

[jeefy]

Definitely.

/close

[k8s-ci-robot]

@jeefy: Closing this issue.

In response to this:

Definitely.

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.