kubernetes-sigs/cluster-api

Release notes for users and provider implementers

Open

#8,051 opened on Feb 2, 2023

View on GitHub
 (10 comments) (1 reaction) (0 assignees)Go (1,532 forks)auto 404
help wantedkind/cleanuppriority/backlogtriage/accepted

Repository metrics

Stars
 (4,267 stars)
PR merge metrics
 (PR metrics pending)

Description

One of the responsibilities of the comms release team is to: "Add docs to collect release notes for users and migration notes for provider implementers".

There was an interesting discussion on this topic in a pr so this is an attempt to move the discussion to a more appropriate place. Recommended background reading in #8015

@sbueringer wrote:

I think we're getting to an interesting point. Essentially we have two docs: one for provider authors one for users. And then we have the difference between those docs being in a draft state or final (or maybe we don't want to distinguish, but I definitely see a difference between the user doc where we would add notes over time and then the final release notes on the release).

So I think we might want a bigger discussions about:

* how do we collect information, e.g.
  
  * add them to docs as part of the PRs making the change
  * putting them in some way in the PR description so they can be automatically pulled from there

* where do we want to publish the final release notes:
  
  * on the GitHub release
  * in docs/CHANGELOG or CHANGELOG like Kubernetes (they then link from a release to the doc)
  * additionally in the book (?)

* how do we distinguish between draft and final state (aka how do we make it visible to our users if the notes are final or just a markdown where we collect information during a release)

* maybe provider and user docs should be just one doc?

Contributor guide