Skip to content

Update and restructure release engineering documentation#2984

Open
saschagrunert wants to merge 2 commits intokubernetes:masterfrom
saschagrunert:fix-release-engineering-docs
Open

Update and restructure release engineering documentation#2984
saschagrunert wants to merge 2 commits intokubernetes:masterfrom
saschagrunert:fix-release-engineering-docs

Conversation

@saschagrunert
Copy link
Copy Markdown
Member

@saschagrunert saschagrunert commented Mar 26, 2026

What type of PR is this:

/kind cleanup
/kind documentation

What this PR does / why we need it:

Two-part update to the release engineering documentation:

Content fixes (commit 1):

  • Replace all SendGrid references with Gmail API (krel announce send)
  • Fix invalid --type=release in krel examples (valid: alpha, beta, rc, official)
  • Add missing --nomock flag to release cut steps
  • Fix testgridshot description to match actual behavior
  • Fill empty sections in go.md, update kube-cross docs
  • Remove stale Content Notice warnings, broken links, TODO comments
  • Update conventions to 1.36 release cycle
  • Fix typos across multiple files

Structural restructure (commit 2):

  • Merge branch-manager.md and patch-release-team.md into a single release-manager.md (roles were consolidated years ago)
  • Extract security/CVE handling into handbooks/security-releases.md
  • Reorganize file layout into handbooks/ (procedural) and reference/ (informational)
  • Rename files for consistency: k8s-release-cut.md -> release-cuts.md, post-release-branch-creation.md -> branch-creation.md, go.md -> go-updates.md
  • Replace Lucidchart SVG with mermaid diagrams
  • Rewrite README.md as a proper documentation index
  • Simplify cherry-pick approval docs to reflect current Prow plugin workflow
  • Remove obsolete spreadsheet tracking section, redirect stub, unused PNG
  • Update all cross-references across the repo
  • Delete role-handbooks/ directory, platforms/guide.md, img/ directory

Which issue(s) this PR fixes:

Fixes #1324
Fixes #1649
Fixes #2291
Fixes #2796
Fixes #2797

Special notes for your reviewer:

New file layout:

release-engineering/
├── README.md                  (documentation index)
├── handbooks/
│   ├── release-manager.md     (merged from branch-manager + patch-release-team)
│   ├── release-cuts.md        (was k8s-release-cut.md)
│   ├── security-releases.md   (new, extracted from branch-manager)
│   ├── branch-creation.md     (was post-release-branch-creation.md)
│   └── go-updates.md          (was go.md)
└── reference/
    ├── artifacts.md
    ├── versioning.md
    ├── platforms.md            (was platforms/README.md)
    ├── baseimage-exception-list.md
    └── gcp.md

/sig release
/area release-eng

@k8s-ci-robot k8s-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. sig/release Categorizes an issue or PR as relevant to SIG Release. area/release-eng Issues or PRs related to the Release Engineering subproject needs-kind Indicates a PR lacks a `kind/foo` label and requires one. labels Mar 26, 2026
@k8s-ci-robot
Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: saschagrunert

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@k8s-ci-robot k8s-ci-robot added approved Indicates a PR has been approved by an approver from all required OWNERS files. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Mar 26, 2026
@saschagrunert saschagrunert force-pushed the fix-release-engineering-docs branch 2 times, most recently from aebec12 to ea64c58 Compare March 26, 2026 14:10
Remove stale SendGrid references and replace with Gmail API,
fix outdated krel command examples, update role terminology
from Branch Manager/Patch Release Team to Release Managers,
correct kube-cross build variables, fill empty handbook
sections, fix broken TOC links, and update testgridshot
description to match actual behavior.

Signed-off-by: Sascha Grunert <sgrunert@redhat.com>
@saschagrunert saschagrunert force-pushed the fix-release-engineering-docs branch from ea64c58 to 6a74d36 Compare March 26, 2026 14:29
@saschagrunert saschagrunert marked this pull request as ready for review March 26, 2026 14:29
@k8s-ci-robot k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Mar 26, 2026
@saschagrunert saschagrunert added priority/important-soon Must be staffed and worked on either currently, or very soon, ideally in time for the next release. kind/documentation Categorizes issue or PR as related to documentation. labels Mar 26, 2026
@k8s-ci-robot k8s-ci-robot removed needs-priority needs-kind Indicates a PR lacks a `kind/foo` label and requires one. labels Mar 26, 2026
@saschagrunert saschagrunert changed the title Update release engineering documentation WIP: Update release engineering documentation Mar 26, 2026
@k8s-ci-robot k8s-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. area/release-team Issues or PRs related to the release-team subproject size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Mar 26, 2026
@saschagrunert saschagrunert force-pushed the fix-release-engineering-docs branch from 7d41a88 to 5accb11 Compare March 26, 2026 15:08
@saschagrunert saschagrunert changed the title WIP: Update release engineering documentation Update and restructure release engineering documentation Mar 26, 2026
@k8s-ci-robot k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Mar 26, 2026
@saschagrunert saschagrunert changed the title Update and restructure release engineering documentation WIP: Update and restructure release engineering documentation Mar 26, 2026
@k8s-ci-robot k8s-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Mar 26, 2026
@saschagrunert saschagrunert force-pushed the fix-release-engineering-docs branch 2 times, most recently from b8ac12c to 3a45129 Compare March 26, 2026 15:19
@saschagrunert saschagrunert changed the title WIP: Update and restructure release engineering documentation Update and restructure release engineering documentation Mar 26, 2026
@k8s-ci-robot k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Mar 26, 2026
Reorganize into handbooks/ and reference/ directories.
Merge branch-manager.md and patch-release-team.md into
release-manager.md. Extract security content into
security-releases.md. Rewrite README.md as documentation
index with mermaid diagrams. Fix technical inaccuracies
across all docs. Update all cross-references. Remove
obsolete content.

Signed-off-by: Sascha Grunert <sgrunert@redhat.com>
@saschagrunert saschagrunert force-pushed the fix-release-engineering-docs branch from 3a45129 to 693b262 Compare March 26, 2026 15:26
@saschagrunert
Copy link
Copy Markdown
Member Author

@kubernetes/release-engineering PTAL

1 similar comment
@saschagrunert
Copy link
Copy Markdown
Member Author

@kubernetes/release-engineering PTAL

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. area/release-eng Issues or PRs related to the Release Engineering subproject area/release-team Issues or PRs related to the release-team subproject cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. kind/documentation Categorizes issue or PR as related to documentation. priority/important-soon Must be staffed and worked on either currently, or very soon, ideally in time for the next release. sig/release Categorizes an issue or PR as relevant to SIG Release. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

2 participants