Add docs for updating Go

docs/developer/updating-go.md

@@ -0,0 +1,22 @@
+# Updating Alloy to a new Go version
+
+There is more to updating Go than simply updating the `go.mod` file.
+You will need to submit two pull requests:
+
+1. [Create a new build image.][build-image-instructions]
+2. Update Alloy to use the new Go version, and the new build image.
+   See [this][example-pr] pull request for an example.
+   At this point you can just search and replace all instances of the old version with the new one.
+   For example, "1.22.1" would be replaced with "1.22.5".
+
+The Go image which is used may sometimes have a name, like "bullseye". 
+The origins of the name are explained in more detail in [Go's DockerHub repository][go-dockerhub]:
+
+> Some of these tags may have names like bookworm or bullseye in them. 
+> These are the suite code names for releases of Debian⁠ and indicate which release the image is based on. 
+> If your image needs to install any additional packages beyond what comes with the image, 
+> you'll likely want to specify one of these explicitly to minimize breakage when there are new releases of Debian.
+
+[build-image-instructions]:../../tools/build-image/README.md
+[go-dockerhub]:https://hub.docker.com/_/golang
+[example-pr]:https://github.com/grafana/alloy/pull/1256/files

tools/build-image/README.md

@@ -3,20 +3,44 @@
 The Grafana Alloy build images are used for CI workflows to manage builds of
 Grafana Alloy.
 
-There are the following images:
+There are several [images][alloy-build-image-dockerhub]:
 
 * `grafana/alloy-build-image:vX.Y.Z` (for building Linux containers)
-* `grafana/alloy-build-image:vX.Y.Z-boringcrypto` (for building Linux containers with boringcrypto)
+* `grafana/alloy-build-image:vX.Y.Z-boringcrypto` (currently unused, may be used for building Linux containers with boringcrypto)
 * `grafana/alloy-build-image:vX.Y.Z-windows` (for building Windows containers)
 
 (Where `X.Y.Z` is replaced with some semantic version, like 0.1.0).
 
-## Pushing new images
+[alloy-build-image-dockerhub]:https://hub.docker.com/repository/docker/grafana/alloy-build-image/general
 
-Once a commit is merged to main which updates the build-image Dockerfiles, a
-maintainer must push a tag matching the pattern `build-image/vX.Y.Z` to the
-grafana/alloy repo. For example, to create version v0.1.0 of the build images,
-a maintainer would push the tag `build-image/v0.1.0`.
+## Creating new images
+
+### Step 1: Update the main branch
+
+Open a PR to update the build images. 
+See [this][example-pr] pull request for an example.
+You need to change the following files:
+ * `tools/build-image/Dockerfile`
+ * `tools/build-image/windows/Dockerfile`
+ * `.drone/drone.yaml`
+ * `.drone/pipelines/build_images.jsonnet`
+ * `.github/workflows/check-linux-build-image.yml`
+
+[example-pr]:https://github.com/grafana/alloy/pull/1241/files
+
+### Step 2: Create a Git tag
+
+After the PR is merged to `main`, a maintainer must push a tag matching the pattern 
+`build-image/vX.Y.Z` to the `grafana/alloy` repo. 
+For example, to create version `0.1.1` of the build images,
+a maintainer would push the tag `build-image/v0.1.1`:
+
+```
+git checkout main
+git pull
+git tag -s build-image/v0.1.1
+git push origin build-image/v0.1.1
+```
 
 Automation will trigger off of this tag being pushed, building and pushing the
 new build images to Docker Hub.