📖 WIP Restructure release docs stack #9906
Conversation
k8s-ci-robot
added
cncf-cla: yes
|
/area release |
k8s-ci-robot
added
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 |
|
We're probably talking about different docs :) I was talking about these: (or rather the ones that remain there like release-cycle.md) And they seem to be neither
I'm in general fine with whatever you want to do here as a release team. I just found it strange to have a docs folder in a |
|
@cahillsf @sbueringer I've updated as per the suggestions. :) |
SubhasmitaSw
force-pushed
the
release-docs-restructure
branch
from
21c5ab7 to
af496fb
Compare
|
👋 right now the
|
k8s-ci-robot
added
size/XL
SubhasmitaSw
changed the title
SubhasmitaSw
force-pushed
the
release-docs-restructure
branch
2 times, most recently
from
ee11a76 to
d1e5f80
Compare
There was a problem hiding this comment.
can you update filename for consistency (README.md)
There was a problem hiding this comment.
let's lowercase the CI here in the filename (ci-signal-bug...)
There was a problem hiding this comment.
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.
we can remove these headers in all three directories' READMEs (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.
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.
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.
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.
can you standardize the filename here as well
|
this comment is also outstanding:
|
SubhasmitaSw
force-pushed
the
release-docs-restructure
branch
2 times, most recently
from
6152f7c to
20a0b16
Compare
|
@cahillsf The PR should be updated, please let me know if there's anything I missed/misunderstood. |
k8s-ci-robot
added
the
needs-rebase
SubhasmitaSw
force-pushed
the
release-docs-restructure
branch
from
088976f to
334dcfa
Compare
k8s-ci-robot
added
size/XL
| # 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.
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.
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.
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.
| - 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.
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.
| - 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.
| - 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.
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.
do we have any particular docs about comms workflow?
k8s-ci-robot
added
the
needs-rebase
SubhasmitaSw
force-pushed
the
release-docs-restructure
branch
from
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 |
SubhasmitaSw
force-pushed
the
release-docs-restructure
branch
from
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. |
SubhasmitaSw
force-pushed
the
release-docs-restructure
branch
from
334dcfa to
8f468c2
Compare
k8s-ci-robot
removed
the
needs-rebase
SubhasmitaSw
force-pushed
the
release-docs-restructure
branch
2 times, most recently
from
c15429c to
2a147fb
Compare
SubhasmitaSw
force-pushed
the
release-docs-restructure
branch
from
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.
this looks like a typo, can retain the original wording:
| - 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.
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
| - 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.
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
| 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.
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
| - [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.
both of these sections appear to have been dropped from the content:
cluster-api/docs/release/release-tasks.md
Line 327 in af7ef29
|
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 |
k8s-ci-robot
added
the
needs-rebase
|
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 |
k8s-ci-robot
added
the
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 filecc @cahillsf