sigs.k8s.io/gateway-api@v1.0.0/RELEASE.md (about)

     1  # Release Process
     2  
     3  ## Overview
     4  
     5  The 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  
     9  This repository is the home for both of the above components.
    10  
    11  ## Versioning strategy
    12  The versioning strategy for this project is covered in detail in [the release
    13  documentation].
    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  
    21  To simplify release notes generation, we recommend using the [Kubernetes release
    22  notes generator](https://github.com/kubernetes/release/blob/master/cmd/release-notes):
    23  
    24  ```
    25  go install k8s.io/release/cmd/release-notes@latest
    26  export GITHUB_TOKEN=your_token_here
    27  release-notes --start-sha EXAMPLE_COMMIT --end-sha EXAMPLE_COMMIT --branch main --repo gateway-api --org kubernetes-sigs
    28  ```
    29  
    30  This output will likely need to be reorganized and cleaned up a bit, but it
    31  provides a good starting point. Once you're satisfied with the changelog, create
    32  a 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
    34  release.
    35  
    36  ### Release Steps
    37  
    38  The following steps must be done by one of the [Gateway API maintainers][gateway-api-team]:
    39  
    40  For 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  
    60  For 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  
    76  For 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
    93  Gateway API follows the standard kubernetes image promotion process described [here][kubernetes-image-promotion]. 
    94  
    95  1. 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.
    97  2. 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`
   103  3. Create a PR with the above changes.
   104  4. 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