docs: Add how to release doc

Author: jimmidyson

devbox.json

@@ -35,6 +35,7 @@
     "path:./hack/flakes#go-mod-upgrade",
     "path:./hack/flakes#golangci-lint",
     "path:./hack/flakes#goprintconst",
+    "path:./hack/flakes#release-please",
     "path:./hack/flakes#setup-envtest"
   ],
   "shell": {

docs/content/contributing/releasing.md

@@ -0,0 +1,49 @@
++++
+title = "Releasing"
++++
+
+This project uses [release-please] to automate changelog updates per release. Due to security restrictions[^1] in the
+`nutanix-cloud-native` GitHub organization, the release process is a little more complex than just using the
+[release-please-action].
+
+When a release has been cut, a new release PR can be created manually using the `release-please` CLI locally. This needs
+to be run by someone with write permissions to the repository. Create the `release-please` branch and PR:
+
+```bash
+make release-please
+```
+
+This will create the branch and release PR. From this point on until a release is ready, the `release-please-action`
+will keep the PR up to date (GHA workflows are only not allowed to create the original PR, they can keep the PR up to
+date).
+
+When a release is ready, the commits in the release PR will need to be signed (again, this is a security requirement).
+To do this, check out the PR branch locally:
+
+```bash
+gh pr checkout <RELEASE_PR_NUMBER>
+```
+
+Sign the previous commit:
+
+```bash
+git commit --gpg-sign --amend
+```
+
+And force push:
+
+```bash
+git push --force-with-lease
+```
+
+The PR will then need the standard 2 reviewers and will then be auto-merged, triggering the release jobs to run and push
+relevant artifacts and images.
+
+[^1]: Specifically, GitHub Actions workflows are not allowed to create or approve PRs due to a potential security flaw.
+    See [this blog post][cider-sec] for more details, as well as the [Security Hardening for GitHub Actions
+    docs][gha-security-hardening].
+
+[release-please]: https://github.com/googleapis/release-please/
+[release-please-action]: https://github.com/google-github-actions/release-please-action
+[cider-sec]: https://medium.com/cider-sec/bypassing-required-reviews-using-github-actions-6e1b29135cc7
+[gha-security-hardening]: https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions

hack/flakes/flake.nix

@@ -81,6 +81,19 @@
               "-X" "sigs.k8s.io/cluster-api-provider-aws/v2/version.gitTreeState=clean"
             ];
           };
+
+          release-please = buildNpmPackage rec {
+            pname = "release-please";
+            version = "16.10.2";
+            src = fetchFromGitHub {
+              owner = "googleapis";
+              repo = "release-please";
+              rev = "v${version}";
+              hash = "sha256-5EST9dNB59wZ9NSHx7V8pAZsws0Py3Q73R6MxvS7zFA=";
+            };
+            npmDepsHash = "sha256-HZAjBF4dH8JTgJrDrXtxJLyAfKKGn9P5fGBSILx00b8=";
+            dontNpmBuild = true;
+          };
         };
 
         formatter = alejandra;

make/dev.mk

@@ -37,3 +37,12 @@ dev.update-bootstrap-credentials-aws:
 	kubectl patch secret capa-manager-bootstrap-credentials -n capa-system -p="{\"data\":{\"credentials\": \"$$(clusterawsadm bootstrap credentials encode-as-profile)\"}}"
 	kubectl rollout restart deployment capa-controller-manager -n capa-system
 	kubectl rollout status deployment capa-controller-manager -n capa-system
+
+.PHONY: release-please
+release-please:
+ifneq ($(GIT_CURRENT_BRANCH),main)
+	$(error "release-please should only be run on the main branch")
+else
+	release-please release-pr \
+	  --repo-url $(GITHUB_ORG)/$(GITHUB_REPOSITORY) --token "$$(gh auth token)"
+endif