- Kubernetes Release Team: Release Notes
- Overview:
- Prerequisites for Release Notes Lead and Shadows
- Tasks and Responsibilities
- Manage permissions
- Setup the Tools and Generate the Release Notes
- Periodically review and fix new release notes
- Attend Release Meetings and follow #sig-release
- Maintain the Known Issues Issue
- Ensure Major Themes are Reflected in the Notes
- Get feedback from SIG Leads
- Clean up and edit the final document
- Curate the External Dependencies Section
- Release Cycle Milestone Activities:
- Tools
- TODOs
The Release Notes role is responsible for collecting and fine-tuning release-notes from the many contributions to Kubernetes between release cycles. This role is likely to find that work during the first several weeks of the release cycle is very laid back with the bulk of the tasks being completed at the end, once the release is firmed up.
The release lead will be responsible for introducing shadows to the team and the release notes subcommand in krel and may ask shadows to run it and make the update PR’s. The release notes lead should indicate pain points and known issues to the shadows (if there are any) and work on strategies for overcoming them to avoid their coalescence during the later weeks.
If there are potential fixes to the issues indicated and team members are keen, fixes and automation of the process is very welcome but not expected.
Before continuing on to the Release Notes specific requirements listed below, please review and work through the tasks in the Release Team Onboarding Guide.
- Strong written and verbal communications skills
- A working knowledge of Kubernetes concepts
- Project management experience is helpful but not required
- The release notes lead should take the Inclusive Speaker Orientation (LFC101) training course
Compared to other release team roles, release notes is one of the least time intensive roles.
In the first week of the release cycle, the Release Notes Lead will organize an onboarding session with the shadows to go over general responsibilities and expectations.
In the first 8 weeks of the cycle, the Release Notes team must attend weekly release meetings and run the release-notes subcommand of krel for every alpha, beta and rc to create an early draft of the release notes. This ensures that the overall quality of the release notes can be verified from the beginning of the release cycle.
This period has an increase in release team meetings each week and there is also significantly more work to do to ensure the release notes are in good working order for the release.
The release-notes subcommand of krel must continue to be run on the release branch (for beta and rc releases) in order to pull in any outstanding PRs that are merged between the beginning of code freeze and the release.
As well as becoming a member of the kubernetes GitHub organization as discussed in the Release Team Onboarding Guide, release notes members should ensure that they become members of the kubernetes-sigs GitHub organization. The tooling used by the release notes team creates pull requests kubernetes and kubernetes-sigs repositories, so membership of both is needed to streamline reviews.
Install Go in your machine and follow the instructions to build the release tools in your machine. Check the system requirements in the krel documentation.
Fork the following repositories to your GitHub account, and clone them using SSH:
kubernetes/sig-release: This is where you will push regular PRs to keep the Release Notes draft up to date.kubernetes-sigs/release-notes: This repo has the release notes website sources
Release Notes lead should be responsible for granting team members required access:
- Add OWNERS file into release notes directory. Sample PR for v1.25 release.
- Add release notes team members for CHANGELOG review/approval. Sample PR for v1.25 release.
- Typically, the release lead updates the release-team-release-notes GitHub team along with other teams in a single PR; check the PR and make sure the release notes team has been updated, otherwise open a PR yourself Sample PR.
The main task of the Release Notes team is the generation of the release notes during the release cycle.
At least one member of the Release Notes Team should be responsible for setting up and running the release-notes subcommand of krel to generate the release notes after each Patch Release:
- Update the release notes draft, a markdown file which will become the final document which will encompass all release notes written by contributors during the current release cycle. See previous drafts for versions 1.25, v1.24 or v1.23.
Detailed instructions for generating the release notes bundle is in the krel release-notes subcommand documentation.
The Release Notes team must make sure that the final document includes well written and informative release notes. To achieve a high-quality document the team should review and edit the
notes by running krel release-notes --fix weekly or as often as development pace
demands.
This command will enable the team to review each release note and edit the note's data. It is recommended that the team splits the work among all members and runs the editing flow on a weekly or biweekly basis. More information about the editing flow can be found in a separate document detailing the editing process and tooling.
The general style guide for release notes includes checking for:
- Past tense: Release notes should be written in the past tense since the changes have already been implemented.
- Technical jargon: While the notes are generally user-friendly, some technical terms like "VAC" or "scheduling hints" could be explained briefly with backticks or double quotes for users unfamiliar with them.
- Additional context: In some cases, providing more context about the problem these changes address or the specific situations where they're relevant could be helpful for understanding their significance. You can find additional context referenced in the PR in k8s/k8s repo to check what the PR does for end users.
Additional style guidelines can be found in the Documentation Style Guide.
The Release Notes Lead and Shadows attend burn down meetings, SIG Release meetings and follow the #sig-release Slack channel for relevant information throughout the release cycle.
A "Known Issues Umbrella Issue" for the release must be created by the release notes team in kubernetes/kubernetes so issues can be collected for the "Known Issues" section of the release notes. See previous known issues for 1.25, 1.24, v1.23, v1.22, v1.21, v1.19, v1.18 or v1.17.
The Communications team will hold a meeting to discuss Major Themes sometime around Code Freeze. Ensure that at least one person from the Release Notes team attends this meeting with the Release Lead and Enhancements Lead. The Release Notes team should ensure that the "Major Themes" identified in this meeting are reflected in the "Major Themes" section of the release notes. If no one is able to attend the meeting, reach out to the Communications team, Release Lead or Enhancements Lead to ensure messaging around Major Themes is coordinated.
Around Code Freeze, the Release Notes team will get in touch with the SIG Leads to ensure that the Release Notes accurately reflect the major themes for their SIGs. The team will also ensure that major issues captured in the release notes are confirmed by the SIG leads before release day.
If gentle nudging of SIG Leads is not effective in retrieving feedback/confirmation, the Release Notes Team can use a reasonable amount of creative liberty in completing the notes.
The confirmed notes are cleaned up and copy edited by the release-notes team to ensure uniform language/style is used. The team must make sure that the final document conforms to the Documentation Style Guide.
A "Dependencies" section should be curated which outlines how external dependency versions have changed since the last release. These changes are currently automatically aggregated, but should still be manually validated for correct content and formatting.
Begin running release-notes tool for the ongoing collection of release notes with the first alpha release, which has been cut directly after the latest minor.
- Update the
release-notes-draft.md - Verify release notes are available on (relnotes.k8s.io)[https://relnotes.k8s.io/]
- Begin attending release team meetings
- Informal intro meeting with release notes team to discuss contact information and logistics
- Begin attending burndown meetings
- Same as above, but generate the notes for each
alphaandbeta. Announce in the #release-notes channel when the release notes PR is ready for review.
- Coordinate with Release Comms to ensure major themes of the release are checked in before Code Freeze; reach out to SIGs and release leads if additional coordination is needed.
- Create known issues issue in
kubernetes/kubernetesto capture known issues for the release. - Share created doc with release-team
- Send an email to SIG-leads to ensure major changes for their SIGs are accurately reflected in the release notes
- Start determining major themes for release notes template to send to SIG-leads
- Repeat previous tasks until the final copy is complete
- Ensure "known issues" section is incorporated into a final document
- Finalize subteam lead for subsequent release
- Work with SIG-leads to finalize major themes for release-notes
- Copy edit notes for spelling, grammar and uniform style
- Start attending daily burndown meetings
- Release day
- Final version of release notes committed for release
- Close the Known Issues Issue and make sure everything has been resolved
- Release Notes must be merged into master prior to the release. If this is not done the release will include the latest draft.
- Keep an eye on the #release-notes channel for any requests for any questions, edits or missed release notes.
- Release retrospective participation
- Update the Release Notes Team Handbook to include any tool documentation, debugging tips, etc. that were discovered during the release cycle
- Update the TODOs section at the end of each release for the next Release Notes Team
- krel The Kubernetes Release Toolbox
- The krel
release-notessubcommand - The old release notes tool
- Release notes website
- go-modiff
- Hackmd
- LWKD (consider contributing to LWKD as part of your role)
- Kubernetes Documentation Style Guide
If you are having trouble running the krel tool, here are some common issues and solutions:
- Try running with
--log-level=debugor--log-level=traceto get more information about what is going wrong. - A temp directory gets created at
/var/folders/7t/273pt80d51l70mj4rxznq_lm0000gn/T/<k8s-hash>when thekreltool is called. If this data is stale, you can try clearing to remove old data withrm -rf /var/folders/7t/273pt80d51l70mj4rxznq_lm0000gn/T/k8s
Checkout the documentation for the krel release-notes subcommand.
All the release notes for a release are stored under the releases directory in the sig-release repo.
For each release there is a JSON and markdown file that contains the collected release notes across path releases. For example, the 1.30 release markdown file contains all the correctly formatted release notes text for the 1.30 release. The JSON file contains the release notes metadata that is used to generate the markdown file.
When a release notes team member runs the krel release-notes command, a new session is created so that you can pause and resume
the editing process. For example the 1.30 release notes sessions are stored in the sessions
directory in the sig-release repo under release-1.30.
If a release notes team member finds a mistake in the release notes, the edit will be saved as a map yaml file in the maps directory. These maps are used to generate the markdown file and JSON file with the correctly edited release note.
As a Release Notes shadow, if you are interested in contributing to the improvement of the release notes process, consider the following areas of improvement:
- YAML linter to block invalid yaml merging in from manually edited release notes. If suggestions are commited that have
invalid yaml, the krel tool will not be able to be run on the next release until the error is fixed in a separate pr.
See example PR from the 1.30 release that unblocked the
v1.30.0-alpha.3release. - Spell check based on dictionary of common Kubernetes terms.
- Check for correct punctuation in release notes.
- Check for incorrect tense in release notes.
- Look into using Vale.sh or the Valve GitHub action to add editorial checks to the release notes PR
Some initial work has been done in this GitHub workflow to introduce checks for common issues in release notes. Here is an example run of the workflow for the 1.30.0-alpha2 release. This is a good starting point for further improvements.
If any team members have NLP experience, implement functionality in release-notes tool to automatically process language in generated release notes file
Goals:
- Generate uniform style across release notes (ie. past tense, formatting).
- Decrease copy editing time.
The idea is to build a continuous release notes improvement process to train a machine learning model to classify. release notes as good or bad. The input for the model should be created continuously during the whole release cycle. by Release Notes Team of SIG Release. See the issue for more details.
- Update krel tool to show progress of how many PRs to review are left and other bugs.