Skip to content

Commit

Permalink
docs: add a release process document
Browse files Browse the repository at this point in the history
This is based on the process followed to create the recent release and
should serve as a guide in case someone else does a future release.

Signed-off-by: John Mulligan <[email protected]>
  • Loading branch information
phlogistonjohn committed Jun 3, 2024
1 parent d3873ad commit ff81382
Showing 1 changed file with 186 additions and 0 deletions.
186 changes: 186 additions & 0 deletions docs/release-process.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,186 @@
# samba-operator Release Process

## Preparation

The samba-operator project has a dedicated branch, called `release`, for
release versions. This is done to update files, in particular the tags of the
default containers in `internal/conf`, that control dependencies. Tags are
applied directly to this branch and only this branch.


Prior to tagging, we must update the `release` branch to "contain" all the
latest changes from the `master` branch. We do this by merging `master` into
`release`.
Example:

```
git checkout master
git pull --ff-only
git checkout release
git pull --ff-only
git merge master
# resolve any conflicts
```

Now we need to update the versions of the containers that the operator deploys
by default. Edit `internal/conf/config.go` to update the versions of
the samba-server, samba-metrics, and svcwatch containers if there are new
released versions for these images.

> [!IMPORTANT]
> The projects that the samba-operator includes/depends on must be released
> *before* the samba-operator. As a policy the "SINK" team releases the projects
> as a group. See the section below for guidance with regards to these projects
> and version numbers.
The direct dependencies of the samba-operator are container images from the
samba-container, svcwatch, and smbmetrics projects. These projects also have
dependencies. The resulting recommended release order for these projects are:
# [sambacc](https://github.com/samba-in-kubernetes/sambacc) - a dependency of samba-container
# [samba-container](https://github.com/samba-in-kubernetes/samba-container) - a dependency of samba-operator and smbmetrics
# [smbmetrics](https://github.com/samba-in-kubernetes/smbmetrics) - a dependency of samba-operator
# [svcwatch](https://github.com/samba-in-kubernetes/svcwatch) - a dependency of samba-operator
# samba-operator

When selecting a project for release, if we plan on releasing operator v0.6 we
first release, for example, samba-containers v0.6, and so on. If a project is
unchanged we do not need to make a release and the older version number will
continue to be used. If we do need to make a release that was not part of the
previous group we may *skip* version numbers. For example if component X was
released as v0.3 in along with samba-operator v0.3 but was unchanged for
operator v0.4 we would release it as v0.5 along with samba-operator v0.5 if a
release is needed for that project.

Once the dependency image tags have been updated, commit the change. For example:
```
git commit -s -p -m 'release: use v0.5 tag for samba-server and samba-metrics images'
```

Run `git push` to push the change to the release branch on GitHub, initiating
a CI test run. Verify the release branch build passes the tests.

In the meantime, edit the file `config/manager/manager.yaml` to bump up
the version of the operator image tag (to match the upcoming tag). This file
is used when deploying the operator and must be configured to deploy
the intended release version. Commit the change with a command like so:
```
git commit -s -p -m 'release: use v0.5 tag for samba-operator by default'
```

### Tagging

Assuming the CI has passed the tests, apply a new tag to the `release` branch:
```
git tag -a -m 'Release v0.5' v0.5
```

This creates an annotated tag. Release tags must be annotated tags.

### Build

With the tag recorded in git we can now build the final image for this release.
This tag and the corresponding hash will be recorded in the binary that is
built.

It is very important to ensure that base images are up-to-date.
You can either purge your local system of cached container images or
inspect the `Dockerfile` and purge or explicitly pull each base image.

Run `make image-build`.

Verify that the tag was properly recorded by the binary in the container.
* Run `podman run --rm -it quay.io/samba.org/samba-operator:latest`
* The operator will fail to start because it is not running in Kubernetes.
However, all you need to verify is that the first log line, with
"Initializing Manager", contains JSON values that have the correct tag in the
"Version" field.


For the image that was just built, apply a temporary pre-release tag
to it. Example:
```
podman tag quay.io/samba.org/samba-operator:{latest,v0.5pre1}
```

Log into quay.io. Push the images to quay.io using the temporary tag. Example:
```
podman push quay.io/samba.org/samba-operator:{latest,v0.5pre1}
```

Wait for the security scan to complete. There shouldn't be any issues if you
properly updated the base images before building. If there are issues and you
are sure you used the newest base images, check the base images on quay.io and
make sure that the number of issues are identical. The security scan can take
some time, while it runs you may want to do other things.


## GitHub Release

When you are satisfied that the tagged version is suitable for release, you
can push the tag to the public repo:
```
git push --follow-tags
```

Draft a new set of release notes. Select the recently pushed tag. Start with
the auto-generated release notes from GitHub (activate the `Generate release
notes` button/link). Add an introductory section (see previous notes for an
example). Add a "Highlights" section if there are any notable features or fixes
in the release. The Highlights section can be skipped if the content of the
release is unremarkable (e.g. few changes occurred since the previous release).

Each release provides a YAML file that can be used to deploy the operator
on a Kubernetes cluster. Generate this file by running:
```
# replace example version with correct version number
kustomize build config/default/ > samba-operator-v0.5-default.yaml
```

Prepare a "downloads" section for the release notes.
Use the following partial snippet as an example. The container details must
reference the image that was pushed to quay.io in an earlier step.
```
## Download
The samba-operator image can be acquired from the quay.io image registry:
* By tag: quay.io/samba.org/samba-operator:v0.5
* By digest: quay.io/samba.org/samba-operator@sha256:040307f53c3f3fd6a5935306f9898858b6c46b7e9c2ae46244e79c2bc42fef0d
### Deploying the operator
This operator can be deployed using the example file samba-operator-v0.5-default.yaml file, attached to this release. Example:
kubectl apply -f samba-operator-v0.5-default.yaml
This is equivalent to checking out the v0.5 tag from the git repository and using the default configuration. Example:
git clone -b v0.5 https://github.com/samba-in-kubernetes/samba-operator
cd samba-operator
kubectl apply -k config/default
```

The tag is pretty obvious - it should match the image tag (minus any pre-release
marker). You can get the digest from the tag using the quay.io UI (do not use
any local digest hashes). Click on the SHA256 link and then copy the full
manifest hash using the UI widget that appears.

Update the "Deploying the operator" section to use the correct version number
and ensure that the YAML file is uploaded to GitHub.

Perform a final round of reviews, as needed, for the release notes and then
publish the release.

Once the release notes are drafted and then either immediately before or after
publishing them, use the quay.io UI to copy each pre-release tag to the "latest"
tag and a final "vX.Y" tag. Delete the temporary pre-release tags using the
quay.io UI as they are no longer needed.


## Announcements

As the samba-operator is typically the final release in the group of "SINK"
projects that are released now is a good time to announce the releases.
Currently the team sends email to the `samba` and `samba-technical` lists at
lists.samba.org. See the list archives for previous examples.

0 comments on commit ff81382

Please sign in to comment.