Update and restructure release engineering documentation

.github/ISSUE_TEMPLATE/post-release-branch-creation.md

@@ -11,7 +11,7 @@ labels: sig/release, area/release-eng
 
 <!--
 
-Follow the docs here: https://github.com/kubernetes/sig-release/blob/master/release-engineering/handbooks/post-release-branch-creation.md
+Follow the docs here: https://github.com/kubernetes/sig-release/blob/master/release-engineering/handbooks/branch-creation.md
 
 Help? Ring @release-managers on slack!
 

.github/ISSUE_TEMPLATE/release-manager.md

@@ -98,7 +98,7 @@ As you work through the checklist, use the following PRs as guides:
       - `release-managers-private@`
   - [ ] `kubernetes/publishing-bot` `OWNERS_ALIASES`
     - Add entry in the `release-engineering-approvers` section
-- [ ] Manually grant permission to post on [kubernetes-announce](https://groups.google.com/forum/#!forum/kubernetes-announce) see (mailing-list-permissions)[https://github.com/kubernetes/sig-release/blob/master/release-engineering/role-handbooks/branch-manager.md#mailing-list-permissions]
+- [ ] Manually grant permission to post on [kubernetes-announce](https://groups.google.com/forum/#!forum/kubernetes-announce) see [mailing-list-permissions](https://github.com/kubernetes/sig-release/blob/master/release-engineering/handbooks/release-manager.md#mailing-list-permissions)
 - [ ] Manually add to the [Release Team Google Group](https://groups.google.com/a/kubernetes.io/g/release-team)
 - [ ] Update Slack `release-managers` User Group [(`kubernetes/community`)](https://git.k8s.io/community/communication/slack-config/sig-release/usergroups.yaml)
 -->

README.md

@@ -30,5 +30,5 @@ Several of the responsibilities of SIG Release are discharged by the Release Tea
 The following high-level descriptions of SIG Release processes should provide a
 general overview about the work we're doing:
 
-- [Release Notes](/release-engineering/release-notes.md)
-- [Versioning](/release-engineering/versioning.md)
+- [Release Notes](/release-engineering/README.md#release-notes)
+- [Versioning](/release-engineering/reference/versioning.md)

release-engineering/handbooks/post-release-branch-creation.md → release-engineering/handbooks/branch-creation.md

@@ -1,8 +1,7 @@
-# Post release branch creation
+# Branch Creation
 
 <!-- toc -->
-- [Post release branch creation](#post-release-branch-creation)
-  - [Checklist](#checklist)
+- [Checklist](#checklist)
     - [Remove EOL version jobs from test-infra (optional)](#remove-eol-version-jobs-from-test-infra-optional)
     - [Update milestone applier rules and check milestone requirements](#update-milestone-applier-rules-and-check-milestone-requirements)
     - [Update Kubekins-e2e v2 variants](#update-kubekins-e2e-v2-variants)
@@ -20,7 +19,7 @@
   - [Notes](#notes)
 
 This document details the tasks that need to be executed after cutting a Kubernetes rc.0 release. These tasks ensure proper configuration for the new release branch and testing infrastructure.
-They must be executed after the `nomock release` is completed, and the release branch is created, as stated in the [branch creation chapter](k8s-release-cut.md#next-release-branch-creation) of the release cut handbook.
+They must be executed after the `nomock release` is completed, and the release branch is created, as stated in the [branch creation chapter](release-cuts.md#next-release-branch-creation) of the release cut handbook.
 
 PR can be created beforehand (and this is recommended in order to get reviews in a timely manner) but you got to remember to put a `/hold` on all the PRs, they have to be lifted only once the `nomock` release phase is done and the branch is created.
 
@@ -101,7 +100,7 @@ variants:
     BAZEL_VERSION: 3.4.1
 ```
 
-Before proceding with the next step, wait for the `post-test-infra-push-kubekins-e2e` postsubmit to finish. You can check the status on [the Prow Status page](https://prow.k8s.io/?job=post-test-infra-push-kubekins-e2e).
+Before proceeding with the next step, wait for the `post-test-infra-push-kubekins-e2e` postsubmit to finish. You can check the status on [the Prow Status page](https://prow.k8s.io/?job=post-test-infra-push-kubekins-e2e).
 
 ### Update release branch jobs in kubernetes/test-infra for the new release and create the dashboards
 
@@ -222,7 +221,7 @@ The k8s-ci-builder needs to be updated in a similar fashion:
       CONFIG: '1.34'
       GO_VERSION: '1.24.5'
       GO_VERSION_TOOLING: '1.24.5'
-      OS_CODENAME: 'bullseye'
+      OS_CODENAME: 'bookworm'
    ```
 
 3. Submit your PR and wait for review and merge
@@ -353,9 +352,9 @@ Generally speaking, update scripts and documentation as needed to ensure they ar
 
 ## Additional Resources
 
-- [Release Manager Handbook](https://github.com/kubernetes/sig-release/blob/master/release-engineering/role-handbooks/branch-manager.md)
+- [Release Manager Handbook](https://github.com/kubernetes/sig-release/blob/master/release-engineering/handbooks/release-manager.md)
 - [Example 1.34.0-rc.0 Release Cut Issue](https://github.com/kubernetes/sig-release/issues/2824)
-- [Example of post branch creation tasks issue for 1.34.0-rc.0](https://github.com/kubernetes/sig-release/issues/2826) _this also contains an example of each PR linkedin in the body of the issue_
+- [Example of post branch creation tasks issue for 1.34.0-rc.0](https://github.com/kubernetes/sig-release/issues/2826) _this also contains an example of each PR linked in the body of the issue_
 - [Slack Discussion Thread for 1.33.0-rc.0](https://kubernetes.slack.com/archives/CJH2GBF7Y/p1744125003875769) - _do not rely on the Slack thread being long lived, if it got archived or the channel got deleted, you should just rely on the docs and the PRs linked in this document_
 
 ## Notes

release-engineering/handbooks/go.md → release-engineering/handbooks/go-updates.md

@@ -7,7 +7,6 @@ various interdependent repositories that need to be updated in tandem.
 - [Scope](#scope)
 - [Signaling intent](#signaling-intent)
 - [kube-cross image](#kube-cross-image)
-  - [kube-cross image building](#kube-cross-image-building)
   - [kube-cross image promotion](#kube-cross-image-promotion)
 - [k8s-cloud-builder image](#k8s-cloud-builder-image)
 - [`kubernetes/kubernetes` updates](#kuberneteskubernetes-updates)
@@ -65,49 +64,87 @@ Some broad requirements (which can be expanded as we get more people involved):
 
 ## kube-cross image
 
-- the image that we use within kubernetes/kubernetes that allows cross compilation builds
-- it has to have the same go version that we're intending to bump Kubernetes to
-Relevant files to create a PR:
-- https://github.com/kubernetes/release/blob/master/images/build/cross/
-  - Dockerfile
-  - variants.yaml: update KUBE_CROSS_VERSION, e.g. "KUBE_CROSS_VERSION: 'v1.14'"
-  - Makefile:
-        these values must default to the current version (or prevailing minor version)
-        *e.g.
-        CONFIG?=go1.14
-        KUBE_CROSS_VERSION?=v1.14*
-- Sending this PR will trigger kube-cross image building
-
-### kube-cross image building
-
-Test Infra
-https://github.com/kubernetes/test-infra/blob/master/config/jobs/image-pushing/k8s-staging-build-image.yaml (don't have to change anything)
-
-- we use GCP builder
-- we only trigger these jobs on changes on the relevant directory (kubecross dir, in this case); images don't need to be built all the time
-- See Testgrid dashboard for job performance details, which lead to GCP(@ k8s-staging-build-image) (Note: a privileged account is needed to access the Execution Details)
-- Copy the docker image digest from GCP
+The `kube-cross` image provides the cross-compilation toolchain used to build
+Kubernetes for multiple platforms. It must use the same Go version that
+Kubernetes is being updated to.
+
+To update the image, create a PR in
+[kubernetes/release](https://github.com/kubernetes/release/tree/master/images/build/cross/)
+modifying:
+
+- `variants.yaml`: update `GO_VERSION` and `KUBERNETES_VERSION` for the
+  target variant.
+- `Makefile`: update the default `GO_VERSION` and `KUBERNETES_VERSION` values
+  to match.
+- `default/Dockerfile`: usually no changes needed unless the cross-compilation
+  toolchain itself changes.
+
+Merging the PR triggers the image build via a GCP Cloud Build job configured in
+[kubernetes/test-infra](https://github.com/kubernetes/test-infra/blob/master/config/jobs/image-pushing/k8s-staging-build-image.yaml).
+The build runs automatically on changes to the `images/build/cross/` directory.
 
 ### kube-cross image promotion
 
-- promote the image from staging to production, for it to be an official image
-- create PR in kubernetes/k8s.io
-  - Update the docker image digest and its version tag @ https://github.com/kubernetes/k8s.io/blob/main/registry.k8s.io/images/k8s-staging-build-image/images.yaml
-  - indicate the image, a link to the staging run, signature ( e.g. "Signed off by : Stephen Augustus saugustus@example.com"), CC @kubernetes/release-engineering & relevant reviewers
-  - the structure of the file is structured by the digests' SHAs
+After the image is built in staging, promote it to production by creating a PR
+in [kubernetes/k8s.io](https://github.com/kubernetes/k8s.io):
+
+- Update the image digest and version tag in
+  [`registry.k8s.io/images/k8s-staging-build-image/images.yaml`](https://github.com/kubernetes/k8s.io/blob/main/registry.k8s.io/images/k8s-staging-build-image/images.yaml).
+- Include a link to the staging build run and CC
+  `@kubernetes/release-engineering`.
 
 ## k8s-cloud-builder image
 
+The `k8s-cloud-builder` image is used during the release process to run
+`krel stage` and `krel release` in Google Cloud Build. It is maintained in the
+[kubernetes/release](https://github.com/kubernetes/release/tree/master/images/k8s-cloud-builder)
+repository. When updating Go, ensure that the `k8s-cloud-builder` image is
+rebuilt with the new Go version as part of the overall update.
+
 ## `kubernetes/kubernetes` updates
 
 ### `master` branch updates
 
+To update Go on the `master` branch of `kubernetes/kubernetes`:
+
+1. Ensure the promoted `kube-cross` image is available (see above).
+2. Update the Go version in
+   [`build/build-image/cross/VERSION`](https://github.com/kubernetes/kubernetes/blob/master/build/build-image/cross/VERSION)
+   and related files.
+3. Run `hack/pin-dependency.sh` and `hack/update-vendor.sh` if dependencies
+   require changes for the new Go version.
+4. Verify that all unit, integration, and e2e tests pass with the new version.
+
+Example PRs can be found in the tracking issues linked in the
+[Signaling intent](#signaling-intent) section.
+
 ### Cherry picks
 
+Cherry picking Go updates to release branches follows the same process as any
+other cherry pick (see the
+[cherry pick guide](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md)).
+Before cherry picking a Go update, ensure the prerequisites described in the
+[Minor version updates](#minor-version-updates) section are met for the target
+branch.
+
 ## kubekins and krte images
 
+The `kubekins-e2e` and `krte` images are maintained in
+[kubernetes/test-infra](https://github.com/kubernetes/test-infra). They are used
+by CI jobs and must be updated to use the new Go version after
+`kubernetes/kubernetes` has been updated. Coordinate with
+[SIG Testing](https://github.com/kubernetes/community/tree/master/sig-testing)
+for these updates.
+
 ## `publishing-bot` updates
 
+The [publishing-bot](https://github.com/kubernetes/publishing-bot) publishes
+code from `kubernetes/kubernetes/staging` to downstream repositories. After a Go
+update lands on a branch, the publishing-bot rules may need updating to ensure
+the published modules reference the correct Go version in their `go.mod` files.
+Check the publishing-bot configuration and coordinate with SIG API Machinery if
+changes are needed.
+
 ## Minor version updates
 
 Minor version updates are initially made *only* to the current development branch,