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

Document release notes process & introduce upgrade notes #2487

Merged
merged 5 commits into from
May 31, 2024

Conversation

lambdanis
Copy link
Contributor

@lambdanis lambdanis commented May 30, 2024

Documenting changes introduced in 1.1 release was not a trivial task, so here I'm attempting to improve the process around release & upgrade notes. There are two different aspects:

  1. I documented the existing practices for release-note blurbs and labels in PRs (see docs/content/en/docs/contribution-guide/release-notes.md).
  2. I want to introduce a practice of writing separate upgrade notes for changes that require attention when upgrading Tetragon. Initially I wanted to introduce a dedicated docs page, similar to the one from Cilium. However, I think keeping upgrade notes together with the regular release notes is a better solution, as many users at least skim through the release notes and Tetragon upgrade generally should be simple enough to not require a dedicated docs page. So instead I added an upgrade notes template to the contrib dir and updated the release process.

The first commit should be backported to the stable branches: v1.0 and v1.1.

Also I'm suggesting to stop using the release-note/breaking-changes label (it's not documented here) and highlight any potential breaking changes in the upgrade notes instead (with understanding that breaking changes should be avoided in the first place).

Pinging @cilium/tetragon on this one. All of this makes sense only if Tetragon core developers follow these practices, so please review and comment if you disagree with something.

@lambdanis lambdanis added area/documentation Improvements or additions to documentation release-note/docs This PR updates the documentation. labels May 30, 2024
@lambdanis lambdanis requested review from mtardy and a team as code owners May 30, 2024 12:49
Copy link

netlify bot commented May 30, 2024

Deploy Preview for tetragon ready!

Name Link
🔨 Latest commit 55a1895
🔍 Latest deploy log https://app.netlify.com/sites/tetragon/deploys/6658a1d3e3576500084bdb39
😎 Deploy Preview https://deploy-preview-2487--tetragon.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

@jrfastab
Copy link
Contributor

One nit from PR description. I'm all for not having breaking changes however we may continue to deprecate flags, fields, and metrics as we go. Protobuf definitions and JSON I would consider user facing e.g. in a database somewhere so we probably need to keep those going for a very long time before deprecating.

lambdanis added 2 commits May 30, 2024 16:46
The idea is to write the upgrade notes alongside development, then copy them to
release notes on a release. Instructions will be added soon.

Signed-off-by: Anna Kapuscinska <[email protected]>
@lambdanis lambdanis force-pushed the pr/lambdanis/upgrade-notes branch from 9d5de8b to 4d87622 Compare May 30, 2024 15:50
The guide covers release notes generated from the PRs based on release-note/*
labels, as well as manually written upgrade notes.

The pull request template links to this guide.

Signed-off-by: Anna Kapuscinska <[email protected]>
@lambdanis lambdanis force-pushed the pr/lambdanis/upgrade-notes branch from 4d87622 to 55a1895 Compare May 30, 2024 15:57
lambdanis added 2 commits May 31, 2024 18:53
It's intended to be used in the release process.

Signed-off-by: Anna Kapuscinska <[email protected]>
* Mention isovalent/tetragon-github-tools which we started using for generating
  release notes
* Add instructions for publishing upgrade notes

Signed-off-by: Anna Kapuscinska <[email protected]>
@lambdanis lambdanis force-pushed the pr/lambdanis/upgrade-notes branch from 55a1895 to dc08936 Compare May 31, 2024 17:55
@lambdanis
Copy link
Contributor Author

I split script and release template updates into separate commits because the script should be backported into stable branches too.

Since there are no concerns I'll merge after the CI passes.

@lambdanis lambdanis merged commit fdc619d into cilium:main May 31, 2024
40 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area/documentation Improvements or additions to documentation release-note/docs This PR updates the documentation.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants