1# Release Process
2
3## Overview
4
5The Gateway API project is an API project that has the following two components:
6- Kubernetes Custom Resource Definitions (CRDs)
7- Corresponding Go API in the form of `sigs.k8s.io/gateway-api` Go package
8
9This repository is the home for both of the above components.
10
11## Versioning strategy
12The versioning strategy for this project is covered in detail in [the release
13documentation].
14
15[the release documentation]: https://gateway-api.sigs.k8s.io/concepts/versioning/
16
17## Releasing a new version
18
19### Writing a Changelog
20
21To simplify release notes generation, we recommend using the [Kubernetes release
22notes generator](https://github.com/kubernetes/release/blob/master/cmd/release-notes):
23
24```
25go install k8s.io/release/cmd/release-notes@latest
26export GITHUB_TOKEN=your_token_here
27release-notes --start-sha EXAMPLE_COMMIT --end-sha EXAMPLE_COMMIT --branch main --repo gateway-api --org kubernetes-sigs
28```
29
30This output will likely need to be reorganized and cleaned up a bit, but it
31provides a good starting point. Once you're satisfied with the changelog, create
32a PR. This must go through the regular PR review process and get merged into the
33`main` branch. Approval of the PR indicates community consensus for a new
34release.
35
36### Release Steps
37
38The following steps must be done by one of the [Gateway API maintainers][gateway-api-team]:
39
40For a **PATCH** release:
41- Create a new branch in your fork named something like `<githubuser>/release-x.x.x`. Use the new branch
42 in the upcoming steps.
43- Use `git` to cherry-pick all relevant PRs into your branch.
44- Update `pkg/generator/main.go` with the new semver tag and any updates to the API review URL.
45- Run the following command `BASE_REF=vmajor.minor.patch make generate` which
46 will update generated docs and webhook with the correct version info. (Note
47 that you can't test with these YAMLs yet as they contain references to
48 elements which wont exist until the tag is cut and image is promoted to
49 production registry.)
50- Create a pull request of the `<githubuser>/release-x.x.x` branch into the `release-x.x` branch upstream
51 (which should already exist since this is a patch release). Add a hold on this PR waiting for at least
52 one maintainer/codeowner to provide a `lgtm`.
53- Verify the CI tests pass and merge the PR into `release-x.x`.
54- Create a tag using the `HEAD` of the `release-x.x` branch. This can be done using the `git` CLI or
55 Github's [release][release] page.
56- Run the `make build-install-yaml` command which will generate install files in the `release/` directory.
57 Attach these files to the Github release.
58- Update the `README.md` and `site-src/guides/index.md` files to point links and examples to the new release.
59
60For a **MAJOR** or **MINOR** release:
61- Cut a `release-major.minor` branch that we can tag things in as needed.
62- Check out the `release-major.minor` release branch locally.
63- Update `pkg/generator/main.go` with the new semver tag and any updates to the API review URL.
64- Run the following command `BASE_REF=vmajor.minor.patch make generate` which
65 will update generated docs and webhook with the correct version info. (Note
66 that you can't test with these YAMLs yet as they contain references to
67 elements which wont exist until the tag is cut and image is promoted to
68 production registry.)
69- Verify the CI tests pass before continuing.
70- Create a tag using the `HEAD` of the `release-x.x` branch. This can be done using the `git` CLI or
71 Github's [release][release] page.
72- Run the `make build-install-yaml` command which will generate install files in the `release/` directory.
73 Attach these files to the Github release.
74- Update the `README.md` and `site-src/guides/index.md` files to point links and examples to the new release.
75
76For an **RC** release:
77- Update `pkg/generator/main.go` with the new semver tag and any updates to the API review URL.
78- Run the following command `BASE_REF=vmajor.minor.patch make generate` which
79 will update generated docs and webhook with the correct version info. (Note
80 that you can't test with these YAMLs yet as they contain references to
81 elements which wont exist until the tag is cut and image is promoted to
82 production registry.)
83- Include the changelog update in this PR.
84- Merge the update PR.
85- Tag the release using the commit on `main` where the changelog update merged.
86 This can be done using the `git` CLI or Github's [release][release]
87 page.
88- Run the `make build-install-yaml` command which will generate
89 install files in the `release/` directory.
90- Attach these files to the Github release.
91
92### Promoting images to production registry
93Gateway API follows the standard kubernetes image promotion process described [here][kubernetes-image-promotion].
94
951. Once the tag has been cut and the image is available in the staging registry,
96 identify the SHA-256 image digest of the image that you want to promote.
972. Modify the
98 [k8s-staging-gateway-api/images.yaml](https://github.com/kubernetes/k8s.io/blob/main/registry.k8s.io/images/k8s-staging-gateway-api/images.yaml)
99 file under [kubernetes/k8s.io](https://github.com/kubernetes/k8s.io)
100 repository and add the image digest along with the new tag under the correct
101 component.
102 1. Currently, the following images are included: `admission-server`, `echo-server`
1033. Create a PR with the above changes.
1044. Image will get promoted by [automated prow jobs][kubernetes-image-promotion]
105 once the PR merges
106
107[release]: https://github.com/kubernetes-sigs/gateway-api/releases
108[gateway-api-team]: https://github.com/kubernetes/org/blob/main/config/kubernetes-sigs/sig-network/teams.yaml
109[kubernetes-image-promotion]: https://github.com/kubernetes/k8s.io/tree/main/registry.k8s.io#image-promoter
View as plain text