Merge pull request #225 from Nordix/tuomo/update-releasing-md

📖 update releasing.md

Author: metal3-io-bot

docs/releasing.md

@@ -1,81 +1,114 @@
-# Releasing
+# ip-address-manager releasing
 
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+This document details the steps to create a release for
+`ip-address-manager` aka IPAM.
 
-- [Prerequisites](#prerequisites)
-   - [`docker`](#docker)
-- [Output](#output)
-   - [Expected artifacts](#expected-artifacts)
-   - [Artifact locations](#artifact-locations)
-- [Process](#process)
-   - [Permissions](#permissions)
+## Before making a release
 
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+Things you should do before making a release:
 
-## Prerequisites
+- Uplift controller Go modules to use latest corresponding CAPI modules
+- Uplift any other direct/indirect dependency to close any public
+  vulnerabilities
 
-### `docker`
+## Permissions
 
-You must have docker installed.
+Creating a release requires repository `write` permissions for:
 
-## Output
+- Tag pushing
+- Branch creation
+- GitHub Release publishing
 
-### Expected artifacts
+These permissions are implicit for the org admins and repository admins.
+Release team member gets his/her permissions via `metal3-release-team`
+membership. This GitHub team has the required permissions in each repository
+required to release IPAM. Adding person to the team gives him/her the necessary
+rights  in all relevant repositories in the organization. Individual persons
+should not be given permissions directly.
 
-1. A container image of the ip-address-manager manager
-1. A git tag
-1. A deployment file : ipam-components.yaml
+## Process
 
-### Artifact locations
+IPAM uses [semantic versioning](https://semver.org). For version `v1.x.y`:
 
-1. The container image is found in the registry `quay.io/metal3-io` with an image
-   name of `ip-address-manager` and a tag that matches the release
-   version. The image is automatically built once the release has been created.
+### Repository setup
 
-## Creating a release for IPAM
+Clone the repository:
+`git clone [email protected]:metal3-io/ip-address-manager`
 
-### Process
+or if using existing repository, verify your intended remote is set to
+`metal3-io`: `git remote -v`. For this document, we assume it is `origin`.
 
-For version v0.x.y:
+- If creating a new minor branch, identify the commit you wish to create the
+  branch from, and create a branch `release-1.x`:
+  `git checkout <sha> -b release-1.x` and push it to remote:
+  `git push origin release-1.x` to create it
+- If creating a new patch release, use existing branch `release-1.x`:
+  `git checkout origin/release-1.x`
 
-1. Create the release notes `make release-notes`. Copy the output and sort
-   manually the items that need to be sorted.
-1. Create an annotated tag `git tag -a v0.x.y -m v0.x.y`. To use your GPG
-   signature when pushing the tag, use `git tag -s [...]` instead
-1. Push the tag to the GitHub repository `git push origin v0.x.y`
-   NB: `origin` should be the name of the remote pointing to
-   `github.com/metal3-io/ip-address-manager`
-1. Run `make release` to build artifacts (the image is automatically built by CI)
-1. [Create a release in GitHub](https://help.github.com/en/github/administering-a-repository/creating-releases)
-   that contains the elements listed above that have been created in the `out`
-   folder
-1. Create a branch `release-0.x` for a minor release for backports and bug fixes.
+### Tags
 
-### Permissions
+First we create a primary release tag, that triggers release note creation and
+image building processes.
 
-Releasing requires a particular set of permissions.
+- Create a signed, annotated tag with: `git tag -s -a v1.x.y -m v1.x.y`
+- Push the tags to the GitHub repository: `git push origin v1.x.y`
 
-- Tag push access to the GitHub repository
-- GitHub Release creation access
+This triggers two things:
 
-## Impact on Metal3
+- GitHub action workflow for automated release process creates a draft release
+  in GitHub repository with correct content, comparing the pushed tag to
+  previous tag
+- Quay starts building release image with the release tag
 
-Multiple additional actions are required in the Metal3 project
+We also need to create one or more tags for the Go modules ecosystem:
 
-### Update CAPM3
+- For any subdirectory with `go.mod` in it (excluding `hack/tools`), create
+  another Git tag with directory prefix, ie.
+  `git tag -s -a api/v1.x.y -m api/v1.x.y`.
 
-CAPM3 should use the latest version. Changes are required there to pull the
-latest version.
+### Release artifacts
 
-### Update Metal3-dev-env
+We need to verify all release artifacts are correctly built or generated by
+the release workflow. For a release, we should have the following artifacts:
 
-Metal3-dev-env variables need to be modified. After a major or minor release,
-the new minor version should point to main for
-IPAM and the released version should point to the release branch.
+Git tags pushed:
 
-### Update the image of IPAM in the release branch
+- Primary release tag: `v1.x.y`
+- Go module tag: `api/v1.x.y`
 
-If you just created a release branch (i.e. minor version release), you should
-modify the image for IPAM deployment in this branch to be tagged with the
-branch name. The image will then follow the branch.
+Container images built and tagged at Quay registry:
+
+- [ip-address-manager:v1.x.y](https://quay.io/repository/metal3-io/ip-address-manager?tab=tags)
+
+Files included in the release page:
+
+- A manifest file - `ipam-components.yaml`
+
+### Release notes
+
+Next step is to clean up the release note manually.
+
+- Check for duplicates, reverts, and incorrect classifications of PRs, and
+  whatever release creation tagged to be manually checked.
+- For any superseded PRs (like CAPI uplifts, or commit revertions) that provide
+  no value to the release, create a summary line in `Superseded` section with
+  the PR ids and summary title. This way the changes are acknowledged to be part
+  of the release, but not overwhelming the important changes contained by the
+  release.
+- If the release you're making isn't the latest release (new
+  minor or major, or new patch release in the latest minor release),
+  uncheck the box for latest release.
+- If it is a release candidate (RC) or a pre-release, tick pre-release box.
+- Publish the release.
+
+## Impact on Metal3 if new minor was released
+
+Patch release process is complete, but further additional actions are required
+in the Metal3 project to take in the new major/minor release. These steps are
+documented in
+[CAPM3 release process](https://github.com/metal3-io/cluster-api-provider-metal3/blob/main/docs/releasing.md)
+
+## Announcements
+
+We announce the release in Kubernetes slack on `#cluster-api-baremetal` channel
+and through the `metal3-dev` group mailing list.