Release documentation improvements

Signed-off-by: Derek Nola <derek.nola@suse.com>

docs/release/expanded/build_container.md

@@ -1,7 +1,23 @@
 # Generate Build Container
 
-1. set env variable PATH_TO_KUBERNETES_REPO to the path to your local kubernetes/kubernetes copy: `export PATH_TO_KUBERNETES_REPO="/Users/mtrachier/go/src/github.com/kubernetes/kubernetes"`
-1. set env variable GOVERSION to the expected version of go for the kubernetes/kubernetes version checked out: `export GOVERSION=$(yq -e '.dependencies[] | select(.name == "golang: upstream version").version' $PATH_TO_KUBERNETES_REPO/build/dependencies.yaml)`
-1. set env variable GOIMAGE to the expected container image to base our custom build image on: `export GOIMAGE="golang:${GOVERSION}-alpine3.15"`
-1. set env variable BUILD_CONTAINER to the contents of a dockerfile for the build container: `export BUILD_CONTAINER="FROM ${GOIMAGE}\nRUN apk add --no-cache bash git make tar gzip curl git coreutils rsync alpine-sdk"`
-1. use Docker to create the build container: `echo -e $BUILD_CONTAINER | docker build -t ${GOIMAGE}-dev -`
+1. set env variable PATH_TO_KUBERNETES_REPO to the path to your local kubernetes/kubernetes copy: 
+    ```
+    export GHUSER="mtrachier"
+    export PATH_TO_KUBERNETES_REPO="/Users/$GHUSER/go/src/github.com/kubernetes/kubernetes"
+    ```
+2. set env variable GOVERSION to the expected version of go for the kubernetes/kubernetes version checked out:  
+    ```
+    export GOVERSION=$(yq -e '.dependencies[] | select(.name == "golang: upstream version").version' $PATH_TO_KUBERNETES_REPO/build/dependencies.yaml)
+    ```
+3. set env variable GOIMAGE to the expected container image to base our custom build image on: 
+    ```
+    export GOIMAGE="golang:${GOVERSION}-alpine"
+    ```
+4. set env variable BUILD_CONTAINER to the contents of a dockerfile for the build container: 
+    ```
+    export BUILD_CONTAINER="FROM ${GOIMAGE}\nRUN apk add --no-cache bash gnupg git make tar gzip curl git coreutils rsync alpine-sdk"
+    ```
+5. use Docker to create the build container: 
+    ```
+    echo -e $BUILD_CONTAINER | docker build -t ${GOIMAGE}-dev -
+    ```

docs/release/expanded/cut_release.md

@@ -12,7 +12,6 @@
 Example Full Command List (this is not a script!):
 ```
 export SSH_MOUNT_PATH="/var/folders/...krzO/agent.452"
-export GLOBAL_GITCONFIG_PATH="/Users/mtrachier/.gitconfig"
 export GLOBAL_GIT_CONFIG_PATH="/Users/mtrachier/.gitconfig"
 export OLD_K8S="v1.22.14"
 export NEW_K8S="v1.22.15"

docs/release/expanded/setup_rc.md

@@ -22,29 +22,33 @@ This guide helps you navigate the creation of those variables.
    1. search for the "golang: upstream version" stanza and the go version is the "version" in that stanza
    1. example: https://github.com/kubernetes/kubernetes/blob/v1.25.1/build/dependencies.yaml#L90-L91
 1. set GOIMAGE to the go version followed by the alpine container version
-   1. example: "golang:1.16.15-alpine3.15"
+   1. example: "golang:1.16.15-alpine"
    1. the first part correlates to the go version in this example the GOVERSION would be '1.16.15'
-   1. the second part is usually the same "-alpine3.15"
-   1. the prefix the the dockerhub group where this image exists (golang)
+   1. the second part is usually the same "-alpine"
 1. set BUILD_CONTAINER to the contents of a Dockerfile to build the "build container" for generating the tags
    1. the FROM line is the GOIMAGE
    1. the only other line is a RUN which adds a few utilities: "bash git make tar gzip curl git coreutils rsync alpine-sdk"
-   1. example: BUILD_CONTAINER="FROM golang:1.16.15-alpine3.15\n RUN apk add --no-cache bash git make tar gzip curl git coreutils rsync alpine-sdk"
+   1. example: BUILD_CONTAINER="FROM golang:1.16.15-alpine\n RUN apk add --no-cache bash git make tar gzip curl git coreutils rsync alpine-sdk"
 1. I like to set this to a file and source it, it helps in case you need to set it again or to see what you did
    1. example:
       ```
-        export SSH_MOUNT_PATH="/var/folders/m7/1d53xcj57d76n1qxv_ykgr040000gp/T//ssh-dmtrX2MOkrzO/agent.45422"
-        export GLOBAL_GITCONFIG_PATH="/Users/mtrachier/.gitconfig"
-        export GLOBAL_GIT_CONFIG_PATH="/Users/mtrachier/.gitconfig"
-        export OLD_K8S="v1.22.13"
-        export NEW_K8S="v1.22.14"
-        export OLD_K8S_CLIENT="v0.22.13"
-        export NEW_K8S_CLIENT="v0.22.14"
-        export OLD_K3S_VER="v1.22.13-k3s1" 
-        export NEW_K3S_VER="v1.22.14-k3s1"
-        export RELEASE_BRANCH="release-1.22"
-        export GOPATH="/Users/mtrachier/go"
-        export GOVERSION="1.16.15"
-        export GOIMAGE="golang:1.16.15-alpine3.15"
-        export BUILD_CONTAINER="FROM golang:1.16.15-alpine3.15\n RUN apk add --no-cache bash git make tar gzip curl git coreutils rsync alpine-sdk"
-        ```
+      export SSH_MOUNT_PATH="/var/folders/m7/1d53xcj57d76n1qxv_ykgr040000gp/T//ssh-dmtrX2MOkrzO/agent.45422"
+  
+      export OLD_K8S="v1.22.13"
+      export NEW_K8S="v1.22.14"
+      export OLD_K8S_CLIENT="v0.22.13"
+      export NEW_K8S_CLIENT="v0.22.14"
+      export OLD_K3S_VER="v1.22.13-k3s1" 
+      export NEW_K3S_VER="v1.22.14-k3s1"
+      export RELEASE_BRANCH="release-1.22"
+      export GOVERSION="1.16.15"
+      export GOIMAGE="golang:1.16.15-alpine"
+      # On Linux
+      export GLOBAL_GIT_CONFIG_PATH="$HOME/.gitconfig"
+      export GOPATH="$HOME/go"
+      # On Mac
+      export GLOBAL_GIT_CONFIG_PATH="/Users/mtrachier/.gitconfig"
+      export GOPATH="/Users/mtrachier/go"
+      
+      export BUILD_CONTAINER="FROM golang:1.16.15-alpine\n RUN apk add --no-cache bash gnupg git make tar gzip curl git coreutils rsync alpine-sdk"
+      ```

docs/release/expanded/tagging.md

@@ -2,20 +2,23 @@
 
 1. run the tag.sh script
    1. the tag.sh script is in the commits that exist in the k3s-io/kubernetes copy but not the kubernetes/kubernetes copy
-   1. when we fetched all from both copies to our local copy we got the tag.sh
-   1. when we rebased our local copy the tag.sh appears in HEAD
-   1. the tag.sh requires a strict env to run in, which is why we generated the build container
-   1. we can now run the tag.sh script in the docker container
-   1. `docker run --rm -u $(id -u) --mount type=tmpfs,destination=${GOPATH}/pkg -v ${GOPATH}/src:/go/src -v ${GOPATH}/.cache:/go/.cache -v ${GLOBAL_GIT_CONFIG_PATH}:/go/.gitconfig -e HOME=/go -e GOCACHE=/go/.cache -w /go/src/github.com/kubernetes/kubernetes ${GOIMAGE}-dev ./tag.sh ${NEW_K3S_VER} 2>&1 | tee tags-${NEW_K3S_VER}.log`
-1. the tag.sh script builds a lot of binaries and creates a commit in your name
-   1. this can take a while, like 45min in my case
-1. the tag.sh script creates a lot of tags in the local copy
-1. the "push" output from the tag.sh is a list of commands to be run
-   1. you should review the commits and tags that the tag.sh creates
-   1. always review automated commits before pushing
-1. build and run the push script
-   1. there is a lot of output, but only about half of it are git push commands, only copy the commands to build a "push" script
-   1. after pasting the push commands to a file, make the file executable
-   1. make sure you are able to push to the k3s-io/kubernetes repo, this is where you will be pushing the tags and commits
-   1. make sure to set the REMOTE env variable to "k3s-io" before running the script
-   1. the push script pushes up the tags and commits from your local copy to the k3s-io/kubernetes copy
+   2. when we fetched all from both copies to our local copy we got the tag.sh
+   3. when we rebased our local copy the tag.sh appears in HEAD
+   4. the tag.sh requires a strict env to run in, which is why we generated the build container
+   5. we can now run the tag.sh script in the docker container:
+      ```
+      docker run --rm -u $(id -u) --mount type=tmpfs,destination=${GOPATH}/pkg -v ${GOPATH}/src:/go/src -v ${GOPATH}/.cache:/go/.cache -v ${GLOBAL_GIT_CONFIG_PATH}:/go/.gitconfig -v ${HOME}/.gnupg:/go/.gnupg -e HOME=/go -e GOCACHE=/go/.cache -w /go/src/github.com/kubernetes/kubernetes ${GOIMAGE}-dev ./tag.sh ${NEW_K3S_VER} 2>&1 | tee tags-${NEW_K3S_VER}.log
+      ```
+2. the tag.sh script builds a lot of binaries and creates a commit in your name
+   - this can take a while, like 45min in my case
+3. the tag.sh script creates a lot of tags in the local copy
+4. the "push" output from the tag.sh is a list of commands to be run. Always review the commits and tags that the tag.sh creates before pushing
+5. build and run the push script
+   1. there is a lot of output, but only about half of it are git push commands, only copy the "git push" commands
+   2. after pasting the push commands to a file, make the file executable
+   3. make sure you are able to push to the k3s-io/kubernetes repo, this is where you will be pushing the tags and commits
+   4. Set the REMOTE env to k3s-io before running the script:
+      ```
+      export REMOTE=k3s-io
+      ```
+   5. Run the push script to add the tags from your local copy to the k3s-io/kubernetes copy

docs/release/kubernetes-upgrade.md

@@ -50,7 +50,7 @@ git rebase --onto ${NEW_K8S} ${OLD_K8S} ${OLD_K3S_VER}~1
 # This command is not backwards compatible and requires versions of yq greater than 4.0, as the query syntax has changed throughout the history of the project.
 export GOVERSION=$(yq -e '.dependencies[] | select(.name == "golang: upstream version").version' build/dependencies.yaml)
 
-export GOIMAGE="golang:${GOVERSION}-alpine3.16"
+export GOIMAGE="golang:${GOVERSION}-alpine"
 
 export BUILD_CONTAINER="FROM ${GOIMAGE}\n \
 RUN apk add --no-cache \
@@ -74,6 +74,7 @@ docker run --rm -u $(id -u) \
 -v ${GOPATH}/src:/go/src \
 -v ${GOPATH}/.cache:/go/.cache \
 -v ${GLOBAL_GIT_CONFIG_PATH}:/go/.gitconfig \
+-e GIT_TRACE=1 \
 -e HOME=/go \
 -e GOCACHE=/go/.cache \
 -w /go/src/github.com/kubernetes/kubernetes ${GOIMAGE}-dev ./tag.sh ${NEW_K3S_VER} 2>&1 | tee ~/tags-${NEW_K3S_VER}.log
@@ -131,8 +132,25 @@ sed -Ei "s/${OLD_K8S_CLIENT}/${NEW_K8S_CLIENT}/g" go.mod
 # since drone perform the builds and tests for the updated tags we no longer need to run make locally.
 # We now update the go.sum by running go mod tidy:
 go mod tidy
-git add go.mod go.sum
 
+# Update the depdencies that we override to match upstream using the ecm-distro-tools script
+curl -s https://raw.githubusercontent.com/rancher/ecm-distro-tools/master/bin/k3s_modsync.sh | sh -
+```
+
+## Validate that K3s builds
+```sh
+SKIP_VALIDATE=1 make
+```
+
+If you run into build issues, you may need to update other repos with forks of upstream components such as:
+- https://github.com/k3s-io/klog
+- https://github.com/k3s-io/cri-dockerd
+- https://github.com/k3s-io/containerd
+
+For these repos, you will need to build and push new tags and then update the go.mod with the new tags.
+
+## Create a PR
+```sh
 git commit --all --signoff -m "Update to ${NEW_K8S}"
 git push --set-upstream origin ${NEW_K3S_VER}
 ```