-
Notifications
You must be signed in to change notification settings - Fork 1.3k
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
📖 WIP Restructure release docs stack #9906
📖 WIP Restructure release docs stack #9906
Conversation
/area release |
docs/release/docs is a strange folder :) |
I can't comment on the moved file somehow. But are you sure you want to move the OWNERS file to docs/release/meta? This means you will lose permissions on docs/release |
@sbueringer Thank you for your views. Do you have anything in mind for the ../docs folder name? |
I would just leave the ones from docs/release/docs in docs/release. Just seems redundant to have a docs folder within a docs folder :) |
here is the kubernetes release example: https://github.com/kubernetes/sig-release/tree/master/release-team i believe the idea here was to split some of these lengthier docs (i.e. https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/release/release-tasks.md) so they are broken up by team. maybe we go with |
@cahillsf @sbueringer I've updated as per the suggestions. :) |
21c5ab7
to
af496fb
Compare
👋 right now the
|
ee11a76
to
d1e5f80
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
overall looking good! thanks for working on this
you can also remove the docs that have been incorporated into the role-handbooks
directory from the docs/release
folder
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
can you update filename for consistency (README.md)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
let's lowercase the CI here in the filename (ci-signal-bug
...)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this is still outstanding
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
apologies, this change might not have gotten added to the previous commit., fixing those.
- [[Continuously] Reduce the amount of flaky tests](#continuously-reduce-the-amount-of-flaky-tests) | ||
- [[Continuously] Bug triage](#continuously-bug-triage) | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
we can remove these headers in all three directories' README
s (the directory structure now indicates the applicable role). the subsequent subheaders can probably then all be bumped up to h2
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this is outstanding as well -- the headers i was referring to are CI Signal/Bug Triage/Automation Manager
, Communications/Docs/Release Notes Manager
and Release Lead
in each of team-specific Readmes
- [Responsibilities](#responsibilities-1) | ||
- [Tasks](#tasks-1) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
these links appear to be broken -- can't find the official doc on this but here's a good stackoverflow reference for how heading anchors work in github markdown: https://stackoverflow.com/questions/27981247/github-markdown-same-page-link
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
seems like the links were removed rather than fixed? i think it would be nice to retain a nav section within each team directory's readme
hi @SubhasmitaSw are you still working on this PR? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
can you standardize the filename here as well
this comment is also outstanding:
|
6152f7c
to
20a0b16
Compare
@cahillsf The PR should be updated, please let me know if there's anything I missed/misunderstood. |
088976f
to
334dcfa
Compare
# role-handbooks | ||
|
||
These handbooks are maintained by current and previous contributors who have staffed these roles. They are intended to be living documents that evolve as the roles and project evolves. Do not treat them as rules set in stone, but guidelines to be re-examined. | ||
|
||
## Overview |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
can we switch the hierarchy here? Overview as the main header and then role handbooks as a secondary section
on second thought, i think we should keep the Onboarding
doc and have it still contain this Overview
but remove the team-specific sections as they are now in the role-handbooks
. then this file will just be the first 3 lines of this doc
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we should keep a first point of context when a first-timer reads this readme first. It should help navigate to role-specific handbooks after an overview of the same.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
its good for context, but the hierarchy doesnt really make sense. we have kind of an aside about role-handbooks as the main header, then the Overview as a subheader.
the suggestion is to maintain the original release-team-onboarding.md
in the parent folder with the overview so that it's an obvious entrypoint in the release docs. then we can include this note on the role-handbooks as a sub-header in that doc, or just have it be on its own in this current doc
cc @kubernetes-sigs/cluster-api-release-team - PTAL as this will restructure docs for all teams |
- [Comms Team](../role-handbooks/communications/README.md) | ||
- [CI Signal Team](../role-handbooks/ci-signal-bug-triage-automation/README.md) | ||
- Check the Release Timeline: | ||
- Go through the [release timeline](../releases/) of the release cycle you are involved in (i.e checkout `release-1.6.md` if you are part of the 1.6 cycle release team) to better understand the key milestones and deadlines. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- Go through the [release timeline](../releases/) of the release cycle you are involved in (i.e checkout `release-1.6.md` if you are part of the 1.6 cycle release team) to better understand the key milestones and deadlines. | |
- Go through the [release timeline](../releases/) of the release cycle you are involved in (i.e reference `release-1.6.md` if you are part of the 1.6 cycle release team) to better understand the key milestones and deadlines. |
nit: in case users are confusing the wording with checking out a branch
## Overview | ||
|
||
- Understand Release Process: | ||
- Get to know how project's release process works. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this might be a bit too general. It could help to reference the release timeline instead and understand how communications come into play there.
|
||
- Understand Release Process: | ||
- Get to know how project's release process works. | ||
- Walk through the [release note generation process](#create-pr-for-release-notes) and try to generate notes by yourself. This is the most important process the comms team is in charge of. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- Walk through the [release note generation process](#create-pr-for-release-notes) and try to generate notes by yourself. This is the most important process the comms team is in charge of. | |
- Walk through the [release note generation process](#create-pr-for-release-notes) and try to generate notes by yourself. |
nit: I think that we can remove this for less clutter as the Overview should be listed by importance.
- Understand Release Process: | ||
- Get to know how project's release process works. | ||
- Walk through the [release note generation process](#create-pr-for-release-notes) and try to generate notes by yourself. This is the most important process the comms team is in charge of. | ||
- Familiarize yourself with the release notes tool [code](https://github.com/kubernetes-sigs/cluster-api/tree/main/hack/tools/release). You'll probably need to update this code during the release cycle to cover new cases or add new features. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- Familiarize yourself with the release notes tool [code](https://github.com/kubernetes-sigs/cluster-api/tree/main/hack/tools/release). You'll probably need to update this code during the release cycle to cover new cases or add new features. | |
- Understand the release notes tool [code](https://github.com/kubernetes-sigs/cluster-api/tree/main/hack/tools/release). The release team is in charge of maintaining this tool and updating it to cover new cases or add new features. |
- Walk through the [release note generation process](#create-pr-for-release-notes) and try to generate notes by yourself. This is the most important process the comms team is in charge of. | ||
- Familiarize yourself with the release notes tool [code](https://github.com/kubernetes-sigs/cluster-api/tree/main/hack/tools/release). You'll probably need to update this code during the release cycle to cover new cases or add new features. | ||
- Documentation familiarity: | ||
- Explore project's documentation and start learning how to update and maintain it. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it would help to list what docs to look at as well as a sample PR for updating it.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
do we have any particular docs about comms workflow?
c46d8cd
to
aec52cd
Compare
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here.
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
aec52cd
to
334dcfa
Compare
@SubhasmitaSw: The following tests failed, say
Full PR test history. Your PR dashboard. Please help us cut down on flakes by linking to an open issue when you hit one in your PR. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. I understand the commands that are listed here. |
334dcfa
to
8f468c2
Compare
c15429c
to
2a147fb
Compare
2a147fb
to
022731b
Compare
- [Continuously: Communicate key dates to the community](#continuously-communicate-key-dates-to-the-community) | ||
- [Communicate beta to providers](#communicate-beta-to-providers) | ||
|
||
❗Notes:his document are based on the v1.6 release cycle. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this looks like a typo, can retain the original wording:
* The examples in this document are based on the v1.6 release cycle. |
- Communication: | ||
- Communicate key d - Communicate key dates to the community | ||
- Documentation:r - Improve release process documentation | ||
- Ensure the book and provider upgrade documentation are up-to-date | ||
- Maintain and improve user facing documentation about releases, release policy and release calendar | ||
- Release Notes:s - Create PR with release notes |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this looks like it got chopped up, should adhere to the original formatting:
cluster-api/docs/release/release-tasks.md
Lines 301 to 308 in af7ef29
* Communication: | |
* Communicate key dates to the community | |
* Documentation: | |
* Improve release process documentation | |
* Ensure the book and provider upgrade documentation are up-to-date | |
* Maintain and improve user facing documentation about releases, release policy and release calendar | |
* Release Notes: | |
* Create PR with release notes |
- Maintain and improve user facing documentation about releases, release policy and release calendar | ||
- Release Notes:s - Create PR with release notes | ||
|
||
## Tasksrelease notes for users and migration notes for provider implementers |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this looks like it got chopped up, should adhere to the original formatting:
cluster-api/docs/release/release-tasks.md
Lines 310 to 312 in af7ef29
### Tasks | |
#### Add docs to collect release notes for users and migration notes for provider implementers |
1. Add a new migration doc for provider implementers. | ||
<br>Prior art: [Add v1. <br>Prior art: [Add v1.5 -> v1.6 migration doc](part of: <https://github.com/kubernetes-sigs/cluster-api/pull/8996>) - see changes to [SUMMARY.md](https://github.com/kubernetes-sigs/cluster-api/pull/8996/files#diff-72d1da5cbeb1afbe684444ec598fbe1815dd2ddc6aa99078ab577cefb9e279ac) and addition of [v1.5-to-v1.6.md](https://github.com/kubernetes-sigs/cluster-api/pull/8996/files#diff-135e34a16773fd40a82b4adbb265444a4fed6c1a973f48d621082b957e7ef93f)ions | ||
|
||
1. Update supported versions in versions.md. | ||
<br>Prior art: [Update s <br>Prior art: [Update supported versions for v1.6](https://github.com/kubernetes-sigs/cluster-api/pull/9119)e new release is available | ||
|
||
The goal of this task to make the book for the current release available under e.g. `https://release-1-6.cluster-api.sigs.k8s.io`. | ||
|
||
1. Add a DNS entry for the book of the new release (should be available under e.g. `https://release-1-6.cluster-api.sigs.k8s.io`). | ||
<br>Prior art: [Add DNS f <br>Prior art: [Add DNS for CAPI release-1.6 release branch](https://github.com/kubernetes/k8s.io/pull/6114).cluster-api.sigs.k8s.io/` and verify that the certificates are valid. If they are not, talk to someone with access to Netlify, they have to [click the `renew certificate` button](https://app.netlify.com/sites/kubernetes-sigs-cluster-api/settings/domain#https) in the Netlify UI. | ||
- To add new subdomains t - To add new subdomains to the certificate config, checkout the email snippet [template](https://github.com/kubernetes-sigs/cluster-api/issues/6017#issuecomment-1823306891) for reference. | ||
3. Update references in introduction.md only on the main branch (drop unsupported versions, add the new release version). <br>Prior art: [Add release 1.5 book link](https://github.com/kubernetes-sigs/cluster-api/pull/9767) to post in Slack | ||
|
||
The goal of this task is to keep the CAPI community updated on recent PRs that have been merged. This is done by using the weekly update tool in `hack/tools/release/weekly/main.go`. Here is how to use it: | ||
|
||
1. Checkout the latest commit on the release branch, e.g. `release-1.6`, or the main branch if the release branch doesn't yet exist (e.g. beta release). | ||
2. Build the release weekly update tools binary. | ||
|
||
```bash | ||
make release-weekl ```basho make release-weekly-update-tooldate with the following command: | ||
|
||
```bash | ||
./bin/weekly --from YYYY-MM-DD --to YYYY-MM-DD --milestone v1.x | ||
``` | ||
|
||
4. Paste the output into a new Slack message in the [`#cluster-api`](https://kubernetes.slack.com/archives/C8TSNPY4T) channel. Currently, we post separate messages in a thread for `main` and the two most recent release branches (e.g. `release-1.5` and `release-1.4`). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this whole section appears to have been improperly formatted, should adhere to the initial formatting:
cluster-api/docs/release/release-tasks.md
Line 310 in af7ef29
### Tasks |
- [Ensure the book for the new release is available](#ensure-the-book-for-the-new-release-is-available) | ||
- [Generate weekly PR updates to post in Slack](#generate-weekly-pr-updates-to-post-in-slack) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
both of these sections appear to have been dropped from the content:
cluster-api/docs/release/release-tasks.md
Line 327 in af7ef29
#### Ensure the book for the new release is available |
additionally there have been a couple of PRs to the docs since you opened this, the updated content should be included in this PR: https://github.com/kubernetes-sigs/cluster-api/commits/main/docs/release |
PR needs rebase. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
seems like the iterations on this PR are a bit spaced out. i have opened this tracking issue so it doesn't get lost across release cycles #10354 if you'd like to continue working on this please assign the issue to yourself and link this PR to the issue @SubhasmitaSw |
The Kubernetes project currently lacks enough contributors to adequately respond to all PRs. This bot triages PRs according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /lifecycle stale |
/close |
@sbueringer: Closed this PR. In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
WRT CAPI Release Team meeting dated: 08/12/2023
Request:
Simplify release docs folder structure: each sub-team could have it’s folder with its own file
cc @cahillsf