diff --git a/.github/scripts/ci-check.sh b/.github/scripts/ci-check.sh index b507c327f..0ab83a318 100755 --- a/.github/scripts/ci-check.sh +++ b/.github/scripts/ci-check.sh @@ -6,6 +6,6 @@ normal=$(tput sgr0) # assert we are running in CI (or die!) if [[ -z "$CI" ]]; then - echo "${bold}${red}This script should ONLY be run in CI. Exiting...${normal}" + echo "${bold}${red}This step should ONLY be run in CI. Exiting...${normal}" exit 1 fi diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 232ce461a..0f8dbe90d 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -125,7 +125,7 @@ jobs: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Build & publish release artifacts - run: make release + run: make ci-release env: # for mac signing and notarization... QUILL_SIGN_P12: ${{ secrets.ANCHORE_APPLE_DEVELOPER_ID_CERT_CHAIN }} diff --git a/Makefile b/Makefile index e830509ae..46423b2bb 100644 --- a/Makefile +++ b/Makefile @@ -315,14 +315,13 @@ changelog: clean-changelog ## Generate and show the changelog for the current u $(CHANGELOG): $(CHRONICLE_CMD) -vvv > $(CHANGELOG) -.PHONY: trigger-release -trigger-release: +.PHONY: release +release: @.github/scripts/trigger-release.sh -.PHONY: release -release: clean-dist $(CHANGELOG) +.PHONY: ci-release +ci-release: ci-check clean-dist $(CHANGELOG) $(call title,Publishing release artifacts) - @.github/scripts/ci-check.sh # create a config with the dist dir overridden echo "dist: $(DIST_DIR)" > $(TEMP_DIR)/goreleaser.yaml @@ -337,6 +336,10 @@ release: clean-dist $(CHANGELOG) # upload the version file that supports the application version update check (excluding pre-releases) .github/scripts/update-version-file.sh "$(DIST_DIR)" "$(VERSION)" +.PHONY: ci-check +ci-check: + @.github/scripts/ci-check.sh + ## Cleanup targets ################################# .PHONY: clean diff --git a/RELEASE.md b/RELEASE.md index 440b66ea9..3e9ba7ab0 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -1,4 +1,39 @@ -# Release Process +# Release + +## Creating a release + +This release process itself should be as automated as possible, and has only a few steps: + +1. **Trigger a new release with `make release`**. At this point you'll see a preview + changelog in the terminal. If you're happy with the changelog, press `y` to continue, otherwise + you can abort and adjust the labels on the PRs and issues to be included in the release and + re-run the release trigger command. + +1. A release admin must approve the release on the GitHub Actions release pipeline run page. + Once approved, the release pipeline will generate all assets and publish a GitHub Release. + +1. If there is a release Milestone, close it. + +Ideally releasing should be done often with small increments when possible. Unless a +breaking change is blocking the release, or no fixes/features have been merged, a good +target release cadence is between every 1 or 2 weeks. + + +## Retracting a release + +If a release is found to be problematic, it can be retracted with the following steps: + +- Deleting the GitHub Release +- Untag the docker images in the `ghcr.io` and `docker.io` registries +- Revert the brew formula in [`anchore/homebrew-syft`](https://github.com/anchore/homebrew-syft) to point to the previous release +- Add a new `retract` entry in the go.mod for the versioned release + +**Note**: do not delete release tags from the git repository since there may already be references to the release +in the go proxy, which will cause confusion when trying to reuse the tag later (the H1 hash will not match and there +will be a warning when users try to pull the new release). + + +## Background A good release process has the following qualities: @@ -7,7 +42,8 @@ A good release process has the following qualities: 1. Allow for different kinds of releases (major breaking vs backwards compatible enhancements vs patch updates) 1. Specify a repeatable way to build and publish software artifacts -## Planning a release + +### Planning a release To indicate a set of features to be released together add each issue to an in-repository Milestone named with major-minor version to be released (e.g. `v0.1`). It is OK for other @@ -25,7 +61,8 @@ release (where some partial or breaking features have already been merged). Unless necessary, feature releases should be small and frequent, which may obviate the need for regular release planning under a Milestone. -## What is in a release + +### What is in a release Milestones are specifically for planning a release, not necessarily tracking all changes that a release may bring (and more importantly, not all releases are necessarily planned @@ -59,7 +96,8 @@ The above suggestions imply that we should: **With this approach as we cultivate good organization of PRs and issues we automatically get an equally good Changelog.** -## Major, minor, and patch releases + +### Major, minor, and patch releases The latest version of the tool is the only supported version, which implies that multiple parallel release branches will not be a regular process (if ever). Multiple releases can @@ -72,33 +110,3 @@ tracking). Semantic versioning should be used to indicate breaking changes, new features, and fixes. The exception to this is `< 1.0`, where the major version is not bumped for breaking changes, instead the minor version indicates both new features and breaking changes. - -## Cutting a release - -Ideally releasing should be done often with small increments when possible. Unless a -breaking change is blocking the release, or no fixes/features have been merged, a good -target release cadence is between every 1 or 2 weeks. - -This release process itself should be as automated as possible, and has only a few steps: - -1. **Trigger a new release with `make trigger-release`**. At this point you'll see a preview - changelog in the terminal. If you're happy with the changelog, press `y` to continue, otherwise - you can abort and adjust the labels on the PRs and issues to be included in the release and - re-run the release trigger command. - -1. A release admin must approve the release on the GitHub Actions release pipeline run page. - Once approved, the release pipeline will generate all assets and publish a GitHub Release. - -1. If there is a release Milestone, close it. - -## Retracting a release - -If a release is found to be problematic, it can be retracted with the following steps: - -- Deleting the GitHub Release -- Untag the docker images in the `ghcr.io` and `docker.io` registries -- Revert the brew formula in [`anchore/homebrew-syft`](https://github.com/anchore/homebrew-syft) to point to the previous release - -**Note**: do not delete release tags from the git repository since there may already be references to the release -in the go proxy, which will cause confusion when trying to reuse the tag later (the H1 hash will not match and there -will be a warning when users try to pull the new release).