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.

Sign up for GitHub

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

Jump to bottom

Update release notes todos section and add debugging tips #2500

Merged
merged 3 commits into from
May 24, 2024
Merged

Update release notes todos section and add debugging tips #2500

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5a39eea
update todos section, add debugging tips
npolshakova May 10, 2024
a301601
pr feedback, add release notes file structure section
npolshakova May 20, 2024
efe1e6a
clean up old responsibilities, add style guide notes
npolshakova May 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 68 additions & 24 deletions release-team/role-handbooks/release-notes/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,8 +76,6 @@ In the first 8 weeks of the cycle, the Release Notes team must attend weekly rel

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 team should use the [template](relnotes-template.md) to organize the raw generated release notes in the Google doc as best as possible and help to guide SIG leads and members in their further editing of the release notes. The final edited release notes should follow this template.

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.

### GitHub Organization Membership
Expand Down Expand Up @@ -128,6 +126,13 @@ It is recommended that the team splits the work among all members and runs the e
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](editing-flow.md).

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](https://kubernetes.io/docs/contribute/style/style-guide/).

### Attend Release Meetings and follow #sig-release

The Release Notes Lead and Shadows attend burn down meetings, SIG Release meetings and follow the [#sig-release](https://kubernetes.slack.com/messages/C2C40FMNF) Slack channel for relevant information throughout the release cycle.
Expand All @@ -152,20 +157,7 @@ The confirmed notes are cleaned up and copy edited by the release-notes team to

### Curate the External Dependencies Section

A "Dependencies" section should be curated which outlines how external dependency versions have changed since the last release. See [the v1.25 release notes](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.25.md#dependencies-1) for an example.

Note that there are [plans in the process to formalize and automate the process of aggregating the changes](https://github.com/kubernetes/community/issues/2234), but this is currently [a very manual process](https://github.com/kubernetes/sig-release/pull/398).

To update an entry in this section the following steps must be performed:

- Pick an entry, for example "Update default etcd server to 3.3.10 for kubernetes 1.14. ([#71615](https://github.com/kubernetes/kubernetes/pull/71615))"
- Open the linked PR 71615 and find which files and lines it modifies
- Open the same files in the `kubernetes/kubernetes` master branch and see if the version changed from v3.3.10
- Look at the history of the file and find which commit / PR changed the version
- Update the entry with the new version and PR URL
- Update the entry message accordingly - if the version has changed or it has been preserved between versions
- The website [lwkd.info](http://lwkd.info/) has weekly Kubernetes updates that often include information about changes in dependencies under a "Version Updates" section
- Kubernetes is released with the completed notes!
A "Dependencies" section should be curated which outlines how external dependency versions have changed since the last release. These changes are currently [automatically aggregated](https://github.com/kubernetes/community/issues/2234), but should still be manually validated for correct content and formatting.

## Release Cycle Milestone Activities:

Expand All @@ -181,7 +173,7 @@ Begin running release-notes tool for the ongoing collection of release notes wit
### Weeks 2 - 10

- Begin attending burndown meetings
- Same as above, but generate the notes for each `alpha` and `beta`
- Same as above, but generate the notes for each `alpha` and `beta`. Announce in the #release-notes channel when the release notes PR is ready for review.

#### Week 10

Expand Down Expand Up @@ -212,13 +204,16 @@ Begin running release-notes tool for the ongoing collection of release notes wit
### Week 17

- __Release day__
- Copy notes from Google Doc to HackMD in markdown
- 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.

### Week 19

- 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
npolshakova marked this conversation as resolved.
Show resolved Hide resolved

## Tools
- [krel](https://github.com/kubernetes/release/tree/master/docs/krel) The Kubernetes Release Toolbox
Expand All @@ -230,17 +225,66 @@ Begin running release-notes tool for the ongoing collection of release notes wit
- [LWKD](http://lwkd.info) *(consider contributing to LWKD as part of your role)*
- [Kubernetes Documentation Style Guide](https://kubernetes.io/docs/contribute/style/style-guide/)

## Debugging Tips

If you are having trouble running the `krel` tool, here are some common issues and solutions:

1. Try running with `--log-level=debug` or `--log-level=trace` to get more information about what is going wrong.
npolshakova marked this conversation as resolved.
Show resolved Hide resolved
2. A temp directory gets created at `/var/folders/7t/273pt80d51l70mj4rxznq_lm0000gn/T/<k8s-hash>` when the `krel` tool is called.
If this data is stale, you can try clearing to remove old data with `rm -rf /var/folders/7t/273pt80d51l70mj4rxznq_lm0000gn/T/k8s`

Checkout the documentation for the [krel `release-notes` subcommand](https://github.com/kubernetes/release/blob/master/docs/krel/release-notes.md).

## Release Notes File Structure

All the release notes for a release are stored under the [releases](https://github.com/kubernetes/sig-release/tree/master/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](https://github.com/kubernetes/sig-release/blob/master/releases/release-1.30/release-notes/release-notes-draft.md)
contains all the correctly formatted release notes text for the 1.30 release. The [JSON file](https://github.com/kubernetes/sig-release/blob/master/releases/release-1.30/release-notes/release-notes-draft.json)
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](https://github.com/kubernetes/sig-release/tree/master/releases/release-1.30/release-notes/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](https://github.com/kubernetes/sig-release/tree/master/releases/release-1.30/release-notes/maps)
directory. These maps are used to generate the markdown file and JSON file with the correctly edited release note.

## TODOs

Update this section at the end of each release for the next Release Notes Team.
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:

#### Github Workflow to Detect Common Release Note Issues

### Post 1.17 TODOs
- 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](https://github.com/kubernetes/sig-release/pull/2446) from the 1.30 release that unblocked the `v1.30.0-alpha.3` release.
- 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](https://vale.sh/) or the [Valve GitHub action](https://github.com/errata-ai/vale) to add editorial checks to the release notes PR

#### If any team members have NLP experience
Some initial work has been done in [this GitHub workflow](https://github.com/npolshakova/sig-release/blob/npolshak/workflow/.github/workflows/release-notes-checker.yaml) to introduce checks for common issues in release notes.
Here is an [example run of the workflow](https://github.com/rudrakshkarpe/sig-release/actions/runs/8073807523/job/22058097731) for the 1.30.0-alpha2 release. This is a good starting point for further improvements.

Implement functionality in release-notes tool to automatically process language in generated release notes file
#### Release Notes tool to automatically process language

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
- Generate uniform style across release notes (ie. past tense, formatting).
- Decrease copy editing time.

#### Release Notes Machine Learning Classifier

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](https://github.com/kubernetes/enhancements/issues/1833) for more details.

#### Krel tool improvements

- Update krel tool to show progress of how many PRs to review are left and other bugs.