SIG Release · Docs Subteam
Kubernetes v1.38
Docs Team
Welcome. Sixteen weeks, five shadows, one release. Here's what we're doing and what you own.
Agenda
What we'll cover
- Who's on the release team, and who's on ours
- What the Docs team ships, and the three weeks people are away
- The dates — published, and the ones we quote
- What you personally own: your KEP slice and your rotations
- Outreach — the reminder ladder
- Release notes — why you never edit the draft, and how you generate them
- Branch sync — four steps, two traps
- Reporting status, and what to do this week
The three in bold are what you'll be doing unaided within a fortnight — they're the ones worth your full attention. Stop me anywhere; we don't have to save questions for the end.
Who we are
Release team
- Sreeram Venkitesh — Release Lead
- Enhancements
- Documentation
- Communications
- Release Signal
- Branch Manager
Us — Docs
- Destiny Erhabor — GMT+1
- Yashasvi Misra — IST
- Subhasmita Swain — GMT+2
- Anshuman Tripathi — PT
- Chiamaka Chielo — GMT+1
- Abraham Alfaro Sosa — UTC−6
Between us we cover
APAC, EMEA and the Americas — which is the point. Work is assigned per-person on the
v1.38 tracking board, Docs view. Your KEPs are the ones with your name in
Docs Assignee.
We ship two things
Documentation
- Find every enhancement that needs docs, track it to merged
- Keep
dev-1.38 in sync with main
- Review docs PRs; get technical accuracy from the owning SIG
- Merge the docs and unfreeze the website on release day
Release notes
- Generate notes for every alpha, beta and rc
- Edit to the style guide all cycle, not at the end
- Collect Known Issues; validate themes with SIG leads
- Land the Final Release Notes PR before the cut
The shape of this cycle
Three weeks where people may be away
- KubeCon China, 7–9 Sep — week 2. Barely affects us.
- KubeCon NA, 9–12 Nov — week 11. KEP owners and SIG reviewers might be hard to reach, so anything we send that week may land flat. Get outreach out before it, and follow up after.
- US Thanksgiving, 26 Nov — week 13. Two days after our ready-for-review deadline, and many SIG Docs approvers are US-based.
Ready-for-review is 24 Nov and Docs Freeze is 3 Dec (AoE). Nine calendar days — but roughly five working days of review capacity for the entire release. Everything we do in weeks 9–12 exists to make that week survivable.
The v1.38 timeline ↗
We work a week ahead of every deadline
Published deadlineOurs — quote this
Placeholder PRs openThu 29 Oct (AoE)Thu 22 Oct
PRs ready for reviewTue 24 NovTue 17 Nov
Docs Freeze — all mergedThu 3 Dec (AoE)Tue 24 Nov
Final Release Notes mergedWed 16 DecMon 14 Dec (AoE)
Those four are ours to hit. These are fixed and we plan around them:
Enhancements Freeze Tue 29 Sep · Code Freeze Mon 16 Nov ·
burndown starts Mon 23 Nov · v1.38.0 ships Wed 16 Dec.
Always quote the right-hand date to a KEP owner. The published date is buffer we never spend — it's what absorbs someone going quiet for a week. Write AoE plus the UTC cutoff, never "EOD", which means nothing across timezones.
What you personally own
Your KEP slice — all cycle
- ~10–14 enhancements, grouped by SIG
- Reminders R1 → R5
- Reviewing the docs PR when it lands
- Keeping the board current — same day, not end of week
- Telling me early when a KEP goes quiet
- Release notes: assignee ≥1×, reviewer ≥1×
- Branch sync — the Friday merge into
dev-1.38
- Meeting updates: by region, APAC or EMEA
- Same week, the Monday summary in
#release-docs — what the team did since last Monday, from the pinned template
- Burndown updates from 23 Nov
By December every one of you should have generated release notes, reviewed them, run two branch syncs, and given two verbal updates.
Right now it's quiet — that's normal
When the work actually starts
1syncWebsite sync — main → dev-1.38, every Friday from now to releaseFridays
2kepsI assign your KEP slice — off the live board, before the freezeby Fri 18 Sep
3notesRelease notes rotation begins — alpha.1 is cutWed 23 Sep
4reachOutreach starts — R1 on the KEP issue: does this need docs?Wed 23 Sep
5finalEnhancements Freeze — list goes final, top up any new KEPs, R2 goes out29 Sep → 1 Oct
6chaseR3, R4, R5 — then the placeholder PR deadline. Busiest stretch of your cycle.8 → 29 Oct
7reviewCode Freeze — the job switches from chasing to reviewing real docs PRsMon 16 Nov
8burnBurndown Mon/Wed/Fri, then daily from 30 NovMon 23 Nov
9landDocs Freeze → final release notes → release day3 → 16 Dec
We start outreach before Enhancements Freeze, not after. A docs PR has to clear a placeholder, a technical review, a SIG Docs review and a merge before the website freezes on 15 Dec. Every week we buy in September is a week that chain isn't compressed in November.
Placeholder PRs · five touches
The reminder ladder
R1boardGitHub on the KEP issue. Does this need docs? Before the freeze.Wed 23 Sep
R2boardGitHub follow-up on the silent and the no-PR, plus any KEP new since the freezeThu 1 Oct
R3slackSlack DM group — first human nudgeThu 8 Oct
R4slackSlack follow-up, and escalate by SIGThu 15 Oct
R5bothFinal call — GitHub and Slack. Internal target.Thu 22 Oct
The channel changes because the problem changes. R1 and R2 are informational and leave a public trail. By R3 they've had the information twice — now it needs a person. An explicit "no docs needed" is as useful to us as a PR — and getting those early is why R1 goes out before the freeze.
Your Fridays are on the sheet
The branch sync, in four steps
1
Branch off dev-1.38
git checkout -b merged-main-dev-1.38-<date> upstream/dev-1.38 — off the dev branch, never off main.
2
Merge main in
git merge upstream/main. Conflicts are normal: keep the dev branch's feature doc, layer main on top.
3
Check before pushing
git log --oneline upstream/dev-1.38..HEAD — one merge commit plus main's. Hundreds means you used the wrong base.
4
PR with base dev-1.38
GitHub defaults the base to main. Change it. This is the step people miss.
One assignee, one reviewer, every tag
Generating the notes
Once per shell. The token is a classic PAT with one scope ticked, and the editor has to be one that blocks:
export GITHUB_TOKEN=$(gh auth token) # PAT: repo → public_repo, nothing else
export EDITOR="code --wait" # must block until you save and close
export PATH=$PATH:$(go env GOPATH)/bin
--fix is the interactive review. It only works alongside --create-draft-pr — and without it you regenerate a raw draft that drops every correction the team has already made:
krel release-notes --create-draft-pr --fix \
--tag=v1.38.0-alpha.1 --fork=<your-gh-user> --nomock
Each note opens in your editor as a YAML map, and every edit you save writes a map file. If the editor doesn't block — plain code, or nano left unsaved — krel reads an empty file, logs "YAML mapfile is blank, ignoring", and your edit is gone with no error. Ctrl+C when you're through the queue or out of time; answer y to "continue from the last session?" next run and it skips what you've already done. Then, before you let it open the PR:
krel release-notes validate --path-to-release-notes ./maps
You need an SSH key on your GitHub account as well. krel pushes the draft branch to your fork over git@github.com — the token only covers the API and opening the PR. Without a key you get Permission denied (publickey) at the push step, after the whole gather has run. Check with ssh -T git@github.com.
Reporting status
GreenOn track. Percentages at target, branch sync current, notes PR merged on time.
YellowNeeds attention or might miss. Below 80% at a checkpoint, one or two missed syncs.
RedWill miss without help. Below 60%, three-plus missed syncs, or a SIG that won't answer.
SIG Docs actively wants yellow and red early — it's in the handbook. Nobody is annoyed by a yellow in week 6. Everybody is annoyed by a surprise in week 13. And be specific: name the KEP and the ask, not "some things are slow".
This week
- Complete the Release Team onboarding guide
- Sign the CLA — new members, open a dummy PR in
contributor-playground now so the bot isn't blocking you later
- Apply for org membership, sponsors @sreeram-venkitesh and @fsmunoz or @katcosgrove
- Join the Slack channels and Google Groups; subscribe to the release calendar
- Fill the OOO tab in the responsibility sheet — any dates you're away, before you pick slots
- Self-assign your rotations in the same sheet — one tab per section, put your name in an open slot. Nobody assigns you
- Install
krel; fork k/website and k/sig-release
- Fork
kubernetes-sigs/reference-docs as well — regenerating the reference is post-release work we all share, not the lead's alone. The process is written up here
- React ✅ in the thread as you finish each one
Time off you already know about goes in the OOO tab — that's what it's for, and it's far easier than swapping a slot later. If something comes up on the day, just tell us 2–3 hours ahead in your timezone. No explanation needed — it only lets us redistribute.
Questions
Ask about any of it
The full written version of this deck has every date, every template, and the outreach walkthrough with screenshots. It's linked in the Slack group along with the responsibility sheet.
We're an inclusive team. If something is unclear, or being a shadow is clashing with your availability, just say so — that's a normal conversation, not a problem.
And if fixing something in this process would make your life easier, do it and open the PR. Both of the last two Docs Leads shipped tooling while they were shadows. The handbook is ours to improve.