Update Doc Handbook for Week 9-11 #2953
+98
−15
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -36,11 +36,11 @@ | |||||
| - [Style Guide Checklist (High to Low Level)](#style-guide-checklist-high-to-low-level) | ||||||
| - [Nominate a Docs Lead for the Next Release](#nominate-a-docs-lead-for-the-next-release) | ||||||
| - [Late-Middle Steps (Weeks 7-8) - Sync with Comms team on the release blog post](#late-middle-steps-weeks-7-8---sync-with-comms-team-on-the-release-blog-post) | ||||||
| - [Late Steps (Weeks 9-11) - Prep for the Release](#late-steps-weeks-9-11---prep-for-the-release) | ||||||
| - [⚠️ Final Release Notes Preparation (CRITICAL TASK)](#️-final-release-notes-preparation-critical-task) | ||||||
| - [Coordinate with SIG Docs for Release Day Support](#coordinate-with-sig-docs-for-release-day-support) | ||||||
| - [Verify SIG Cluster Lifecycle (kubeadm) Documentation](#verify-sig-cluster-lifecycle-kubeadm-documentation) | ||||||
| - [Curate the External Dependencies Section](#curate-the-external-dependencies-section) | ||||||
| - [Update Releases Page (the week before the release)](#update-releases-page-the-week-before-the-release) | ||||||
| - [Release Week (Week 12)](#release-week-week-12) | ||||||
| - [Update the site configuration files for previous releases](#update-the-site-configuration-files-for-previous-releases) | ||||||
|
|
@@ -624,26 +624,108 @@ If unsure, send a message to their [Slack](https://kubernetes.slack.com/messages | |||||
|
|
||||||
| Be congnizant of the status of the release blog post as merging and publishing the release blog post is a significant step on release day e.g., [1.21 release blog](https://github.com/kubernetes/website/pull/27233). | ||||||
|
|
||||||
| ## Late Steps (Weeks 9-11) - Prep for the Release | ||||||
|
|
||||||
| **Time Required:** ~4-6 hours total | ||||||
|
|
||||||
| ### ⚠️ Final Release Notes Preparation (CRITICAL TASK) | ||||||
|
|
||||||
| > [!Important] | ||||||
| > This is a **Docs Lead responsibility** and a **time-intensive task**. Start this process as early as possible (after last Release Note PR is merged), as it can take considerable time depending on the number of release note PRs throughout the cycle. | ||||||
|
Member
There was a problem hiding this comment. Starting after the last Release Notes PR is merged would be too late, as release notes typically diminish after each RC. This process should begin around Docs Freeze, as noted in the calendar, with reviews completed approximately before the final |
||||||
|
|
||||||
| **What:** Perform a comprehensive final review of all release notes to ensure they conform to the [Documentation Style Guide](https://kubernetes.io/docs/contribute/style/style-guide/) and maintain consistent quality. | ||||||
|
|
||||||
| **Process:** This is a manual process to review and clean up the accumulated release notes from the entire release cycle. | ||||||
|
|
||||||
| 1. **Fork and Setup** | ||||||
| ```bash | ||||||
| # Fork kubernetes/sig-release repo (if not already done) | ||||||
| # Clone your fork | ||||||
| git clone https://github.com/${USERNAME}/sig-release.git | ||||||
| cd sig-release | ||||||
|
|
||||||
| # Create a new branch for final release notes review | ||||||
| git checkout -b ${USERNAME}/v[future-release]-final-release-notes-review | ||||||
| ``` | ||||||
|
|
||||||
| 2. **Review and Edit Release Notes Files** | ||||||
| - Navigate to `releases/release-[future-release]/release-notes/` | ||||||
| - Review and edit both files: `release-notes-draft.json` and `release-notes-draft.md` | ||||||
| - Ensure conformance to [Documentation Style Guide](https://kubernetes.io/docs/contribute/style/style-guide/) | ||||||
| - Check: consistent tone, grammar, clarity, appropriate technical detail | ||||||
| - **⚠️ Keep both files in sync with identical changes** | ||||||
|
|
||||||
| 3. **Commit and Create PR** | ||||||
| ```bash | ||||||
| git add releases/release-[future-release]/release-notes/ | ||||||
| git commit -m "Final review and cleanup of v[future-release] release notes" | ||||||
| git push origin ${USERNAME}/v[future-release]-final-release-notes-review | ||||||
| ``` | ||||||
|
|
||||||
| 4. **Open PR for Peer Review** | ||||||
| - Create PR against `kubernetes/sig-release` repository | ||||||
| - Title: `Final review and cleanup of v[future-release] release notes` | ||||||
| - Request review from: | ||||||
| - Docs Team Shadows | ||||||
| - SIG Docs reviewers | ||||||
| - Release Team Lead | ||||||
|
Member
There was a problem hiding this comment. Add to post to chairs-and-techleads channel I dropped this message for v1.36 release
Member
There was a problem hiding this comment. Also, add text to prepare everything before the final week starts i.e with the reviews, lgtm and approval. |
||||||
|
|
||||||
| **Example PR:** [v1.35 Final Release Notes Review](https://github.com/kubernetes/sig-release/pull/2928) | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ### Coordinate with SIG Docs for Release Day Support | ||||||
|
|
||||||
| This is to confirm SIG Docs support availability for release day tasks and ensure generated documentation is ready. | ||||||
|
|
||||||
| **Action Items:** | ||||||
| - Join upcoming SIG Docs meeting (or reach out on [#sig-docs](https://kubernetes.slack.com/messages/sig-docs) if meeting is missed) | ||||||
| - Send coordination message to SIG Docs chairs/leads | ||||||
| - Confirm release day support availability | ||||||
| - Verify generated documentation readiness | ||||||
|
|
||||||
| **Sample Message (post in [#sig-docs](https://kubernetes.slack.com/messages/sig-docs) slack channel and also bring to notice during SIG Docs meeting):** | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| ``` | ||||||
| Hi @sig-docs-leads 👋 | ||||||
|
|
||||||
| The v[future release] release is scheduled for **[Day], [Date] at [Time] [Timezone]**. | ||||||
|
|
||||||
| **Need from SIG Docs:** | ||||||
| 1. **Release day support** - Who can help with Netlify configuration updates and release blog post publication? | ||||||
|
Member
There was a problem hiding this comment. Instead of specifying the task, it would better to draft in a manner where who will be a PoC for helping the docs lead with the tasks, and questions |
||||||
| 2. **Generated docs status** - Please confirm these are ready: Kubernetes API reference, kubectl documentation, components documentation. | ||||||
|
|
||||||
| Thank you! | ||||||
| ``` | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ### Verify SIG Cluster Lifecycle (kubeadm) Documentation | ||||||
|
|
||||||
| This is to ensure kubeadm-related documentation is complete and ready for the release. | ||||||
|
|
||||||
| **Action Items:** | ||||||
| - Validate kubeadm documentation completeness | ||||||
| - Send verification message to [#sig-cluster-lifecycle](https://kubernetes.slack.com/messages/sig-cluster-lifecycle/) slack channel | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| **Sample Message:** | ||||||
|
|
||||||
| ``` | ||||||
| Hi @sig-cluster-lifecycle 👋 | ||||||
|
|
||||||
| v[future release] Docs Lead here. Can someone confirm all kubeadm documentation (upgrade guides, installation docs, changes) are in place for the v[future release] release on [Date]? | ||||||
|
|
||||||
| Thank you! | ||||||
| ``` | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ### Curate the External Dependencies Section | ||||||
|
|
||||||
| 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. | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ### Update Releases Page (the week before the release) | ||||||
|
|
||||||
| Create a PR against the dev-[future-release] branch to add an entry for [future-release] on https://kubernetes.io/releases. | ||||||
|
|
@@ -662,6 +744,7 @@ The following fields are required: | |||||
| Have a Release Manager lgtm the dates on the PR. | ||||||
| This PR can be merged on release day by the Docs lead. | ||||||
|
Member
There was a problem hiding this comment. Could you please move these two lines here This would help set the focus before starting with the updating the files. Could you placed as bullet items with and Actions achor. |
||||||
|
|
||||||
|
|
||||||
| ## Release Week (Week 12) | ||||||
| ⚠️ Everything in this section is important. It's OK to ask for advice if you're not sure. | ||||||
|
|
||||||
|
|
||||||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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 better to drop the time-estimation because the Final Release Note Prep can vary from release to release. We would rather write a line or two of what is expected in these two weeks.