Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Separate Release Notes website #529

Open
jeefy opened this Issue Feb 27, 2019 · 12 comments

Comments

@jeefy
Copy link
Member

jeefy commented Feb 27, 2019

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.

screen shot 2019-02-27 at 3 36 41 pm

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

This comment has been minimized.

Copy link
Member

spiffxp commented Feb 27, 2019

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

This comment has been minimized.

Copy link
Member

BenTheElder commented Feb 27, 2019

kubernetes-sigs/papyros 📜 ✔️

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

@justaugustus

This comment has been minimized.

Copy link
Member

justaugustus commented Mar 8, 2019

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

This comment has been minimized.

Copy link
Member

justaugustus commented Mar 8, 2019

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

@jeefy

This comment has been minimized.

Copy link
Member Author

jeefy commented Mar 8, 2019

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

This comment has been minimized.

Copy link
Member Author

jeefy commented Mar 15, 2019

@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

This comment has been minimized.

Copy link
Member

marpaia commented Mar 16, 2019

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

@jeefy

This comment has been minimized.

Copy link
Member Author

jeefy commented Mar 16, 2019

+100 to Netlify

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

That's building out of my repo for now.

@spiffxp

This comment has been minimized.

Copy link
Member

spiffxp commented Mar 18, 2019

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 comment has been minimized.

Copy link
Contributor

tpepper commented Mar 18, 2019

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

This comment has been minimized.

Copy link
Member Author

jeefy commented Mar 18, 2019

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

This comment has been minimized.

Copy link
Contributor

onyiny-ang commented Mar 19, 2019

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 🎉

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 😅

@justaugustus justaugustus added this to Needs Grooming in SIG Release Mar 19, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.