Document release process

README.md

@@ -46,6 +46,7 @@ Gloo Gateway is a feature-rich, fast, and flexible Kubernetes-native ingress con
 
 ## Contributing to Gloo Gateway
 The [devel](devel) folder should be the starting point for understanding the code, and contributing to the product.
+For maintainer release instructions, see [RELEASE.md](RELEASE.md).
 
 ## Thanks
 **Gloo Gateway** would not be possible without the valuable open-source work of projects in the community. We would like to extend a special thank-you to [Envoy](https://www.envoyproxy.io).

RELEASE.md

@@ -0,0 +1,141 @@
+# Release Process
+
+This document is for maintainers who need to cut a release for `solo-io/gloo`.
+
+## Overview
+
+A release in this repo starts by tagging the target branch and creating the matching GitHub Release. That GitHub Release works together with the repo's release automation: Build Bot / Google Cloud Build publishes the release artifacts such as container images, the Helm chart, and `glooctl` binaries, while release-triggered GitHub Actions handle follow-up tasks such as copying docs and syncing APIs to `solo-apis`. After the automation completes, verify that the expected assets were published and follow up on any failed release jobs.
+
+Relevant implementation details:
+
+- [`cloudbuild.yaml`](cloudbuild.yaml)
+- [`ci/cloudbuild/publish-artifacts.yaml`](ci/cloudbuild/publish-artifacts.yaml)
+- [`Makefile`](Makefile)
+- [`ci/upload_github_release_assets.go`](ci/upload_github_release_assets.go)
+- [`.github/workflows/push-docs.yaml`](.github/workflows/push-docs.yaml)
+- [`.github/workflows/push-solo-apis-branch.yaml`](.github/workflows/push-solo-apis-branch.yaml)
+
+## Release Checklist
+
+1. Start from the branch you intend to release.
+
+   For example, use `main` for the current development line or an LTS branch such as `v1.21.x` for a patch release.
+
+2. Create and push an annotated tag.
+
+   ```bash
+   git checkout <release-branch>
+   git pull --ff-only origin <release-branch>
+   git tag -a vX.Y.Z[-betaN|-rcN] -m "vX.Y.Z[-betaN|-rcN]"
+   git push origin vX.Y.Z[-betaN|-rcN]
+   ```
+
+3. Create the GitHub Release from that tag.
+
+   Use the GitHub Releases UI or `gh release create`.
+   Create it promptly after pushing the tag, and publish it rather than leaving it as a draft.
+
+   ```bash
+   gh release create vX.Y.Z \
+     --repo solo-io/gloo \
+     --verify-tag \
+     --title vX.Y.Z
+   ```
+
+   Add `--prerelease` for beta and release candidate builds.
+
+4. Monitor the release automation.
+
+   There are three important pieces:
+
+   - Build Bot / Cloud Build should run the `publish-artifacts` pipeline. This is the job that publishes images, the Helm chart, and `glooctl` release assets.
+   - `push-docs` runs on `release.created`.
+   - `Push API Changes to solo-apis` runs on `release.published`.
+
+5. Verify the GitHub release assets.
+
+   Expected assets from `publish-glooctl`:
+
+   - `glooctl-linux-amd64`
+   - `glooctl-linux-amd64.sha256`
+   - `glooctl-linux-arm64`
+   - `glooctl-linux-arm64.sha256`
+   - `glooctl-darwin-amd64`
+   - `glooctl-darwin-amd64.sha256`
+   - `glooctl-darwin-arm64`
+   - `glooctl-darwin-arm64.sha256`
+   - `glooctl-windows-amd64.exe`
+   - `glooctl-windows-amd64.exe.sha256`
+
+   Quick check:
+
+   ```bash
+   gh release view vX.Y.Z --repo solo-io/gloo --json assets,url
+   ```
+
+6. Verify follow-up automation.
+
+   - Confirm `push-docs` completed or capture the failure for follow-up.
+   - Confirm `Push API Changes to solo-apis` completed and review the resulting PR in `solo-apis` if one was opened.
+
+## Checking Cloud Build
+
+If the GitHub release exists but assets are still missing, inspect Build Bot / Cloud Build.
+
+The root Cloud Build config submits a child build named `publish-artifacts`, and the child build's `release-chart` step runs `publish-helm-chart` and `publish-glooctl`.
+
+If you have `gcloud` access, start with:
+
+```bash
+gcloud builds list \
+  --project=solo-public \
+  --limit=20 \
+  --sort-by=~createTime \
+  --format='table(id,status,createTime,substitutions.TAG_NAME,substitutions.REPO_NAME,logUrl)'
+```
+
+Then inspect the matching build:
+
+```bash
+gcloud builds describe BUILD_ID \
+  --project=solo-public \
+  --format='yaml(id,status,createTime,finishTime,substitutions,steps.id,logUrl)'
+```
+
+And view logs:
+
+```bash
+gcloud builds log BUILD_ID --project=solo-public
+```
+
+Look for:
+
+- `substitutions.TAG_NAME: vX.Y.Z`
+- the `publish-artifacts` child build
+- the `release-chart` step
+- `publish-glooctl`
+- `upload_github_release_assets.go`
+
+If your team uses a different GCP project for Build Bot, substitute that project name accordingly.
+
+## Common Failure Modes
+
+### The release page exists but has no assets
+
+This usually means the GitHub Release object did not exist when `publish-glooctl` tried to upload assets, or the Cloud Build release job failed.
+
+Fix:
+
+1. Confirm the GitHub Release object exists for the tag.
+2. Inspect the Build Bot / Cloud Build history for that tag.
+3. Re-run or manually trigger the `publish-artifacts` release build if needed.
+
+### `push-docs` fails
+
+This workflow is separate from asset publishing. A `push-docs` failure does not explain missing GitHub release assets by itself.
+
+Check the workflow logs and fix the docs-copy issue independently.
+
+### `Push API Changes to solo-apis` succeeds but no change lands automatically
+
+That workflow pushes to `solo-apis`. Review and approve the resulting `solo-apis` PR if one is created.

changelog/v1.22.2/release-docs.yaml

@@ -0,0 +1,5 @@
+changelog:
+  - type: NON_USER_FACING
+    resolvesIssue: false
+    description: >-
+      Add maintainer release process documentation and link it from the README.