Merge pull request #406 from fluxcd/docs-release-procedure

Add release procedure documentation

docs/dev-guides/source-watcher.md

@@ -10,7 +10,7 @@ events and reacts to revision changes by downloading the artifact produced by
 
 On your dev machine install the following tools:
 
-* go >= 1.13
+* go >= 1.15
 * kubebuilder >= 2.3
 * kind >= 0.8
 * kubectl >= 1.18

docs/internal/release.md

@@ -1,7 +1,126 @@
-# Release
+# Flux release procedure
 
-To release a new version the following steps should be followed:
+The Flux Go modules and the GitOps Toolkit controllers are released by following the [semver](https://semver.org) conventions.
 
-1. Create a `<next semver>` tag form `master` and
+Repositories subject to semver releases:
+
+1. [fluxcd/pkg](https://github.com/fluxcd/pkg)
+    - modules: `apis/meta`, `runtime`, various utilities
+    - dependencies: `k8s.io/*`, `sigs.k8s.io/controller-runtime`
+1. [fluxcd/source-controller](https://github.com/fluxcd/source-controller)
+    - modules: `api`
+    - dependencies: `github.com/fluxcd/pkg/*`
+1. [fluxcd/kustomize-controller](https://github.com/fluxcd/kustomize-controller)
+    - modules: `api`
+    - dependencies: `github.com/fluxcd/source-controller/api`, `github.com/fluxcd/pkg/*`
+1. [fluxcd/helm-controller](https://github.com/fluxcd/helm-controller)
+    - modules: `api`
+    - dependencies: `github.com/fluxcd/source-controller/api`, `github.com/fluxcd/pkg/*`
+1. [fluxcd/notification-controller](https://github.com/fluxcd/notification-controller)
+    - modules: `api`
+    - dependencies: `github.com/fluxcd/source-controller/api`, `github.com/fluxcd/pkg/*`
+1. [fluxcd/flux2](https://github.com/fluxcd/flux2)
+    - modules: `manifestgen`
+    - dependencies: `github.com/fluxcd/source-controller/api`, `github.com/fluxcd/kustomize-controller/api`, `github.com/fluxcd/helm-controller/api`, `github.com/fluxcd/notification-controller/api`,`github.com/fluxcd/pkg/*`
+
+## Release procedure
+
+### Go packages
+
+The Go packages in [fluxcd/pkg](https://github.com/fluxcd/pkg) are dedicated modules, 
+each module has its own set of dependencies and release cycle.
+
+Release procedure for a package:
+
+1. Checkout the `main` branch and pull changes from remote.
+1. Run `make release-<package name> VER=<next semver>`.
+
+### Controllers
+
+A toolkit controller has a dedicated module for its API, the API module 
+has its own set of dependencies.
+
+Release procedure for a controller and its API:
+
+1. Checkout the `main` branch and pull changes from remote.
+1. Create a `api/<next semver>` tag and push it to remote.
+1. Create a new branch from `main` i.e. `release-<next semver>`. This
+   will function as your release preparation branch.
+1. Update the `github.com/fluxcd/<NAME>-controller/api` version in `go.mod`
+1. Add an entry to the `CHANGELOG.md` for the new release and change the
+   `newTag` value in ` config/manager/kustomization.yaml` to that of the
+   semver release you are going to make. Commit and push your changes.
+1. Create a PR for your release branch and get it merged into `main`.
+1. Create a `<next semver>` tag for the merge commit in `main` and
    push it to remote.
 1. Confirm CI builds and releases the newly tagged version.
+
+### Flux
+
+Release procedure for Flux:
+
+1. Checkout the `main` branch and pull changes from remote.
+1. Create a `<next semver>` tag form `main` and push it to remote.
+1. Confirm CI builds and releases the newly tagged version.
+
+## Upgrade Kubernetes modules
+
+Flux has the following Kubernetes dependencies:
+
+- `k8s.io/api`
+- `k8s.io/apiextensions-apiserver`
+- `k8s.io/apimachinery`
+- `k8s.io/cli-runtime`
+- `k8s.io/client-go`
+- `sigs.k8s.io/controller-runtime`
+
+**Note** that all `k8s.io/*` packages must the have the same version in `go.mod` e.g.:
+
+```
+	k8s.io/api v0.19.2
+	k8s.io/apiextensions-apiserver v0.19.2
+	k8s.io/apimachinery v0.19.2
+	k8s.io/cli-runtime v0.19.2
+	k8s.io/client-go v0.19.2
+```
+
+The specialised reconcilers depend on:
+
+- kustomize-controller: `sigs.k8s.io/kustomize/api`
+- helm-controller: `helm.sh/helm/v3`
+
+**Note** that the `k8s.io/*` version must be compatible with both `kustomize/api` and `helm/v3`.
+If there is a breaking change in `client-go` we have to wait for Kustomize and Helm to upgrade first.
+
+Upgrade procedure:
+
+`fluxcd/pkg`:
+
+1. Update the `k8s.io/*` version in `pkg/apis/meta/go.mod`
+1. Release the `apis/meta` package
+1. Update `apis/meta` version in `pkg/runtime/go.mod`
+1. Update the `k8s.io/*` version in `pkg/runtime/go.mod`
+1. Update `sigs.k8s.io/controller-runtime` version in `pkg/runtime/go.mod`
+1. Release the `runtime` package
+
+`fluxcd/source-controller`:
+
+1. Update the `github.com/fluxcd/pkg/apis/meta` version in `source-controller/api/go.mod` and `source-controller/go.mod`
+1. Update the `k8s.io/*` version in `source-controller/api/go.mod` and `source-controller/go.mod`
+1. Update the `sigs.k8s.io/controller-runtime` version in `source-controller/api/go.mod` and `source-controller/go.mod`
+1. Update the `github.com/fluxcd/pkg/runtime` version in `source-controller/go.mod`
+1. Release the `api` package
+
+`fluxcd/<kustomize|helm|notification>-controller`:
+
+1. Update the `github.com/fluxcd/source-controller/api` version in `controller/api/go.mod`  and `controller/go.mod`
+1. Update the `github.com/fluxcd/pkg/apis/meta` version in `controller/api/go.mod` and `controller/go.mod`
+1. Update the `k8s.io/*` version in `controller/api/go.mod`  and `controller/go.mod`
+1. Update the `github.com/fluxcd/pkg/runtime` version in `controller/go.mod`
+1. Release the `api` package
+
+`fluxcd/flux2`:
+
+1. Update the `github.com/fluxcd/*-controller/api` version in `flux2/go.mod`
+1. Update the `github.com/fluxcd/pkg/*` version in `flux2/go.mod`
+1. Update the `k8s.io/*` and `github.com/fluxcd/pkg/runtime` version in `flux2/go.mod`