Cloud Native Computing Foundation KubeCon + CloudNativeCon North America 2018 (Seattle), 15 Dec 2018

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Lightning Talk: Behind The Scenes: Kubernetes Release Notes Tips & Tricks - Mike Arpaia, Kolide

Description

Join us for Kubernetes Forums Seoul, Sydney, Bengaluru and Delhi - learn more at kubecon.io

Don't miss KubeCon + CloudNativeCon 2020 events in Amsterdam March 30 - April 2, Shanghai July 28-30 and Boston November 17-20! Learn more at kubecon.io. The conference features presentations from developers and end users of Kubernetes, Prometheus, Envoy, and all of the other CNCF-hosted projects

Lightning Talk: Behind The Scenes: Kubernetes Release Notes Tips & Tricks - Mike Arpaia, Kolide

This session aims to shed more light on the release note process from the Kubernetes contributor's point of view. We will briefly discuss the entire release note process from PR to release day. We will pay special attention to the labels and prow commands that contributors can (and should!) use to add context to PRs so that the release note automation can most effectively sort and prepare the document. Finally, we will discuss some common copy-editing tips and tricks that you can use to make sure the final document is consistent and helpful for end-users (spoiler: write your note in the past tense!).

To learn more: https://sched.co/GrV1

A

So how's it going everyone, a quick question: is anyone ever or can you raise your hand if you've submitted a PR with a release? Note nice feel for sure so I'm Mara paya, on slack and on github on twitter, I'm, Mike Arpaio, because Mar Pi was taken. So you know nice to meet you all in person, I was on the release team for 111, 112 and 113 working on release, notes and I wrote.

A

This I wrote the outline of this deck well copy, editing the release, notes document for 113, so I also edited out all the snark afterwards, but so, if you're not familiar, I want to just go through the developer process for submitting release, notes and then offer some tips and tricks that you might not be aware of about how you can you know change the way you write release, notes that makes the release team's life easier and makes your release note higher quality.

A

So the process, if you're not familiar if you've ever created a PR against kubernetes, looks a little like this and there is like whole wall of text and you kind of have to go through and fill in all of the questions that it asks you and all the way at the bottom. There's a little block that says: back-to-back-to-back tech release note empty space, and if you have a release note you can fill it in there and if you don't have a release note, ideally you write the word nun now.

A

If you don't write the word nun, this happens and you get the bot saying like hey. You have to either write a release, note or use the prowl command release. Note none! So you do that and that's awesome, and all of this is outlined on this document in kubernetes community repository which isn't super discoverable, but I, guess that's a problem with a lot of kubernetes Community documents. Sometimes so generally everyone does this and towards the end of the release.

A

What happens is there's some tooling that we have that goes through and iterates through all of the pull requests that have landed in master from the last release to when we want to cut the new release and it kind of parses through them looks at each commit sees if the PR that introduced that commit has a release. Note pulls as many labels as we can from that PR and then tries to generate a document, that's as contextualized as possible, given all the labels that you add everything we can infer from her pull request.

A

That's the process now for the tips and tricks. So one thing you might not know about release notes is that you can edit your note after your PR has been merged. So you know pre I'd, say before 1:12. The note that is in that was in your PR used to make it into the actual commit message in master. That's no longer the case, but either way all of the tooling that generates release. Notes documents pulls the note text from your PR at the time of document generation, which is usually at the end of their release.

A

So if you land a PR early in their release- and you don't like the release, note text feel free to go and change it. The other thing is write like you're from the future, so this is an interesting thing that I've thought about a lot as I've changed the tense on various words in people's people's release notes over time. But when you write your PR, you write as if you're from you know, it's very you know if this diff has merged. This will happen and stuff like that, you're writing about the future.

A

But what you have to consider is that when a user is going to be reading a release, note they're going to be reading it in the future in several months from now so right, you know things in the past tense. This thing was bumped, not you know. When this PR is merged, it will be bumped and stuff like that. So you know: I had a counter as I was going through. This last releases notes- and you know this is in order of the top amount of things that I changed now.

A

I do have some tooling to go and edit these automatically, but it's not always. You know you can't always update you can always change update to update it doesn't always work out that way. The other thing that I would implore you to do is use more sig and kind labels. If you can so your sig, if you add like slash sig costs per lifecycle, that'll show you know categorize your note in the cluster life cycle section of the document.

A

If you had multiple SIG's, that's a little less helpful for the release of the document, but still help more helpful than no SIG's. And then you know there are several kind labels that you can use. That'll. Add your note to various sections of the document, which is super useful.

A

The last bits are don't write, notes for non user-facing changes. Now the text and the release notes document says is your feature or do you want to document any user facing changes, so you know, don't be afraid to release? No none and you know capitalize the first letter of the sentence. It's always useful, always helpful and finally use markdown formatting. So if you're referencing a new flag, that's being added or something like that, wrap it in back, ticks and all that good stuff. So that's it with three seconds left. So thank you.