diff --git a/.github/actions/check-go-mod-replace/action.yml b/.github/actions/check-go-mod-replace/action.yml index 63c37ef837..fc742f5af1 100644 --- a/.github/actions/check-go-mod-replace/action.yml +++ b/.github/actions/check-go-mod-replace/action.yml @@ -15,13 +15,15 @@ name: Check go.mod replace directives description: > Fails if the go.mod in the specified directory contains active replace - directives that are not in the allowed list. + directives that are not in the allowed list, or requires one of the given + modules at a pseudo-version (commit date and hash instead of a tag). inputs: working-directory: description: Directory containing the go.mod to check. required: false default: "." + allowed-replacements: description: > JSON array of module paths that are allowed to have replace directives. @@ -29,6 +31,15 @@ inputs: required: false default: "[]" + tagged-only-modules: + description: > + JSON array of module paths that must be required at tagged versions, not + pseudo-versions. Submodules (path/...) are included. Pseudo-versions of + other modules are allowed. + Example: '["github.com/kptdev/kpt"]' + required: false + default: "[]" + runs: using: composite steps: @@ -45,3 +56,20 @@ runs: echo "$UNEXPECTED" | jq . exit 1 fi + + - name: Check for pseudo-versions + shell: bash + working-directory: ${{ inputs.working-directory }} + run: | + TAGGED_ONLY='${{ inputs.tagged-only-modules }}' + # Pseudo-versions end in a 14 digit UTC timestamp and a 12 character commit hash. + PSEUDO=$(go mod edit -json | jq --argjson modules "$TAGGED_ONLY" \ + '[(.Require // [])[] + | select(.Path as $p | $modules | any(. as $m | $p == $m or ($p | startswith($m + "/")))) + | select(.Version | test("[-.][0-9]{14}-[0-9a-f]{12}$"))]') + COUNT=$(echo "$PSEUDO" | jq 'length') + if [ "$COUNT" -gt 0 ]; then + echo "::error::$(pwd)/go.mod requires modules at pseudo-versions. Use tagged versions before releasing." + echo "$PSEUDO" | jq . + exit 1 + fi diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml index ad43f3d20d..ee379f30e1 100644 --- a/.github/workflows/go.yml +++ b/.github/workflows/go.yml @@ -83,6 +83,8 @@ jobs: run: make fix vet fmt lint - name: Test with Coverage run: make test-coverage + - name: Script Tests + run: make test-scripts - name: Docker Runtime Tests run: make test-docker env: diff --git a/.github/workflows/release-api.yml b/.github/workflows/release-api.yml deleted file mode 100644 index 45286ed0c7..0000000000 --- a/.github/workflows/release-api.yml +++ /dev/null @@ -1,43 +0,0 @@ -# Copyright 2026 The kpt Authors -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -name: kpt API release -on: - push: - tags: - - "api/v[0-9]+.[0-9]+.[0-9]+*" - -jobs: - build: - runs-on: ubuntu-latest - name: kpt-api-release - steps: - - name: Checkout - uses: actions/checkout@v6 - with: - fetch-depth: 0 - - name: Set up Go - uses: actions/setup-go@v6 - with: - go-version-file: go.mod - cache-dependency-path: api/go.sum - - name: Check for replace directives in api/go.mod - uses: ./.github/actions/check-go-mod-replace - with: - working-directory: api - - name: Build, test, lint (api module) - run: | - git config --global user.email you@example.com - git config --global user.name Your Name - make api diff --git a/.github/workflows/release-cli.yml b/.github/workflows/release-provenance.yml similarity index 50% rename from .github/workflows/release-cli.yml rename to .github/workflows/release-provenance.yml index 99a12fe0f7..9af3761759 100644 --- a/.github/workflows/release-cli.yml +++ b/.github/workflows/release-provenance.yml @@ -12,16 +12,24 @@ # See the License for the specific language governing permissions and # limitations under the License. -name: kpt CLI release +# Generates SLSA provenance for the assets of the release created by release.yml. +# The recorded revision is the commit of the cli/vX.Y.Z tag. Release events are +# only delivered for releases created with an App or PAT token, which release.yml uses. + +name: kpt release provenance on: - push: - tags: - - "cli/v[0-9]+.[0-9]+.[0-9]+*" + release: + types: [published] + +permissions: + contents: read jobs: - build: + hash: + # Only the CLI releases have assets. + if: startsWith(github.event.release.tag_name, 'cli/v') runs-on: ubuntu-latest - name: kpt-cli-release + name: hash-release-assets outputs: hashes: ${{ steps.hash.outputs.hashes }} steps: @@ -29,45 +37,32 @@ jobs: uses: actions/checkout@v6 with: fetch-depth: 0 - - name: Set up Go - uses: actions/setup-go@v6 - with: - go-version-file: cli/go.mod - - name: Check for replace directives in cli/go.mod - uses: ./.github/actions/check-go-mod-replace - with: - working-directory: cli - - name: Build, Test, Lint + - name: Check that the release tag is on main run: | - git config --global user.email you@example.com - git config --global user.name Your Name - make all - make test-docker - - name: Run GoReleaser - id: run-goreleaser - uses: goreleaser/goreleaser-action@v6 - with: - distribution: goreleaser - version: "~> v2" - args: release --skip=validate --verbose -f release/tag/goreleaser.yaml + git merge-base --is-ancestor "$GITHUB_SHA" origin/main + - name: Download release assets env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GH_TOKEN: ${{ github.token }} + TAG: ${{ github.event.release.tag_name }} + run: | + gh release download "$TAG" --dir release-assets + # Provenance from an earlier run is not an asset to attest. + rm -f release-assets/*.intoto.jsonl - name: Generate SLSA subjects for provenance id: hash run: | set -euo pipefail - checksum_file=$(cat dist/artifacts.json | jq -r '.[] | select (.type=="Checksum") | .path') - - echo "hashes=$(cat $checksum_file | base64 -w0)" >> "$GITHUB_OUTPUT" + hashes=$(cd release-assets && sha256sum -- * | base64 -w0) + echo "hashes=${hashes}" >> "$GITHUB_OUTPUT" provenance: - needs: [build] + needs: [hash] permissions: actions: read # To read the workflow path. id-token: write # To sign the provenance. contents: write # To add assets to a release. uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@v2.0.0 with: - base64-subjects: "${{ needs.build.outputs.hashes }}" - upload-assets: true # upload to a new release + base64-subjects: "${{ needs.hash.outputs.hashes }}" + upload-assets: true # upload to the release that triggered this run diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index fbf6c383ae..a344d258bd 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -12,29 +12,174 @@ # See the License for the specific language governing permissions and # limitations under the License. -name: kpt library release +# Releases the api, root and cli modules with one locked version. +# See release/README.md and scripts/multimodule-release/release.sh. +# +# TODO: The provenance (release-provenance.yml) only attests the published assets, +# not the run that built them. A stricter option: this workflow only validates, +# tests, tags and pushes (keeping the dry run), and a workflow triggered by the +# pushed cli/v* tag builds, releases and attests in one run. That needs the app +# token for the push, protected cli/* tags, and would also allow resuming a +# half-done release by re-running it. +# +# Pushing uses a token of the kptdev-ci-bot GitHub App, created right before it is +# needed because installation tokens expire after an hour. The app secrets should +# also be defined in the "release" environment, which takes precedence over the +# organization secrets and limits who can read them. + +name: kpt multimodule release on: - push: - tags: - - "v[1-9].*.*" + workflow_dispatch: + inputs: + version: + required: true + description: 'The new version to be released, e.g. v1.2.3 or v1.2.3-pre.1' + type: string + dry_run: + required: false + default: false + description: 'Build everything locally, but do not push or publish anything' + type: boolean + +concurrency: + group: kpt-multimodule-release + cancel-in-progress: false + +permissions: + contents: read jobs: build: + # Releases are only made from main. + if: github.ref == 'refs/heads/main' runs-on: ubuntu-latest - name: kpt-library-release + name: kpt-multimodule-release + environment: release + permissions: + contents: write + env: + BRANCH: main + DRY_RUN: ${{ inputs.dry_run }} steps: - name: Checkout uses: actions/checkout@v6 with: + ref: main fetch-depth: 0 + # Push credentials are configured later, with a fresh app token. + persist-credentials: false - name: Set up Go uses: actions/setup-go@v6 with: go-version-file: go.mod - - name: Check for replace directives in go.mod + cache: false + - name: Configure git + run: | + git config --global user.name "github-actions[bot]" + git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com" + - name: Validate version and branch + id: validate + env: + INPUT_VERSION: ${{ inputs.version }} + run: | + version=$(./scripts/multimodule-release/release.sh validate "$INPUT_VERSION" "$BRANCH") + echo "version=${version}" >> "$GITHUB_OUTPUT" + - name: Check for replace directives and kpt pseudo-versions (root module) + uses: ./.github/actions/check-go-mod-replace + with: + working-directory: . + tagged-only-modules: '["github.com/kptdev/kpt"]' + - name: Check for replace directives and kpt pseudo-versions (api module) + uses: ./.github/actions/check-go-mod-replace + with: + working-directory: api + tagged-only-modules: '["github.com/kptdev/kpt"]' + - name: Check for replace directives and kpt pseudo-versions (cli module) + uses: ./.github/actions/check-go-mod-replace + with: + working-directory: cli + tagged-only-modules: '["github.com/kptdev/kpt"]' + - name: Build, Test, Lint + run: | + make all + make test-docker + - name: Create commits and tags + env: + VERSION: ${{ steps.validate.outputs.version }} + run: ./scripts/multimodule-release/release.sh tag "$VERSION" + - name: Check release commits for replace directives and kpt pseudo-versions (root module) + uses: ./.github/actions/check-go-mod-replace + with: + working-directory: . + tagged-only-modules: '["github.com/kptdev/kpt"]' + - name: Check release commits for replace directives and kpt pseudo-versions (api module) + uses: ./.github/actions/check-go-mod-replace + with: + working-directory: api + tagged-only-modules: '["github.com/kptdev/kpt"]' + - name: Check release commits for replace directives and kpt pseudo-versions (cli module) uses: ./.github/actions/check-go-mod-replace - - name: Build, test, lint (root module) + with: + working-directory: cli + tagged-only-modules: '["github.com/kptdev/kpt"]' + - name: Run GoReleaser + uses: goreleaser/goreleaser-action@v6 + with: + distribution: goreleaser + version: "~> v2" + # Only builds: the open-source GoReleaser cannot name the release differently from its tag. + args: release --skip=validate,publish --clean --verbose -f release/tag/goreleaser.yaml + env: + # The root tag, so that .Version (used in the package versions) is X.Y.Z. + GORELEASER_CURRENT_TAG: ${{ steps.validate.outputs.version }} + - name: Create GitHub App token + id: app-token + uses: actions/create-github-app-token@v2 + with: + app-id: ${{ secrets.CI_BOT_APP_ID }} + private-key: ${{ secrets.CI_BOT_PRIVATE_KEY }} + - name: Configure push credentials + env: + APP_TOKEN: ${{ steps.app-token.outputs.token }} + run: | + git remote set-url --push origin "https://x-access-token:${APP_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" + # Before the push, so a failure here leaves no tags behind. Runs in dry runs too. + - name: Prepare release notes and assets + env: + VERSION: ${{ steps.validate.outputs.version }} + GH_TOKEN: ${{ steps.app-token.outputs.token }} + run: | + ./scripts/multimodule-release/release.sh notes "$VERSION" "$BRANCH" release-notes.md + ./scripts/multimodule-release/release.sh assets dist release-assets + + { + echo "## Release ${VERSION} (dry run: ${DRY_RUN})" + echo + echo "### Assets" + echo + (cd release-assets && printf -- '- %s\n' *) + echo + echo "### Release notes" + echo + cat release-notes.md + } | tee -a "$GITHUB_STEP_SUMMARY" + - name: Push branch and tags + env: + VERSION: ${{ steps.validate.outputs.version }} + run: ./scripts/multimodule-release/release.sh push "$VERSION" "$BRANCH" + - name: Create GitHub release + if: ${{ !inputs.dry_run }} + env: + VERSION: ${{ steps.validate.outputs.version }} + GH_TOKEN: ${{ steps.app-token.outputs.token }} run: | - git config --global user.email you@example.com - git config --global user.name Your Name - make lib + prerelease=() + if [[ "$VERSION" == *-* ]]; then + prerelease=(--prerelease) + fi + # The release is named vX.Y.Z but points at the cli/vX.Y.Z tag. + gh release create "cli/${VERSION}" release-assets/* \ + --verify-tag \ + --title "$VERSION" \ + --notes-file release-notes.md \ + "${prerelease[@]}" \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index fb4561b121..dc33f3b74d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -153,9 +153,9 @@ git config --global user.name "Your Name" * **.github/workflows/live-e2e.yml**: Live apply e2e tests * Tests with pinned Kubernetes image SHAs * Runs `make test-live-apply` with `K8S_VERSION` environment variable -* **.github/workflows/release-api.yml**: Release the kpt API module - * Builds, tests and lints the kpt API module - * Runs `make api` +* **.github/workflows/release.yml**: Multimodule release (manual `workflow_dispatch`) + * Tags the api, root and cli modules with one locked version, builds with GoReleaser and publishes the GitHub release + * Implemented by `scripts/multimodule-release/`; see `release/README.md` ### Documentation & Tests diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b819bbed22..9cb30a9472 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -165,9 +165,9 @@ The same checks run with `make -C api all`. For step-by-step maintainer instructions (CLI/library vs API, tag shapes, and CI), see [release/README.md](release/README.md). -- **kpt library** (root module `github.com/kptdev/kpt`): tags look like `v1.2.3`. Pushing one runs the [library release](.github/workflows/release.yml) workflow (`make lib` only). -- **kpt CLI** (`github.com/kptdev/kpt/cli`): tags look like `cli/v1.2.3`, on a commit whose `cli/go.mod` requires the library tag. Pushing one runs the [CLI release](.github/workflows/release-cli.yml) workflow (GoReleaser, images, provenance). -- **kpt API**: publish nested-module **git** tags such as `api/v1.2.3`; consumers pin with `go get github.com/kptdev/kpt/api@v1.2.3` (see [Go modules: VCS version](https://go.dev/ref/mod#vcs-version)). +All three modules (`api/`, the root library and `cli/`) are released together with one version by running the +[multimodule release](.github/workflows/release.yml) workflow manually. It creates the `api/v1.2.3`, `v1.2.3` and `cli/v1.2.3` +tags and the GitHub release `v1.2.3`; do not push these tags by hand. ### Function Catalog diff --git a/Makefile b/Makefile index e200c3539e..9d56da73d6 100644 --- a/Makefile +++ b/Makefile @@ -21,7 +21,7 @@ include ./make/api.mk include ./make/cli.mk include ./make/checks.mk -all: fix vet fmt lint test build tidy +all: fix vet fmt lint test test-scripts build tidy build: cli/build @@ -59,6 +59,13 @@ generate: install-mdtogo api/generate go fmt ./internal/docs/generated/... $(MAKE) schema +# Runs the unit tests of the shell scripts: every scripts/**/test-*.sh. +.PHONY: test-scripts +test-scripts: + @find scripts -name 'test-*.sh' | sort | while read -r t; do \ + echo "=== $$t"; bash "$$t" || exit 1; \ + done + # This target is used to run Go tests that require docker runtime. # Some tests, like pipeline tests, need to have docker available to run. # KRM_FN_RUNTIME can be set to select the desired function runtime. diff --git a/make/checks.mk b/make/checks.mk index c85354ff2a..70eb6d0c36 100644 --- a/make/checks.mk +++ b/make/checks.mk @@ -52,7 +52,7 @@ fix fmt vet lint test tidy: $(MAKE) cli/$@ .PHONY: lib api cli -# lib is what the vX.Y.Z tag workflow runs. It does not build the CLI. +# lib runs the checks of the root module only. It does not build the CLI. lib api cli: $(MAKE) $@/fix $(MAKE) $@/vet diff --git a/release/README.md b/release/README.md index 4910ec5d37..b6da7f4b0d 100644 --- a/release/README.md +++ b/release/README.md @@ -1,64 +1,100 @@ # Releasing -This document covers releases of the **root library** (`github.com/kptdev/kpt`), the **CLI** (`github.com/kptdev/kpt/cli`), and the **API module** ([`github.com/kptdev/kpt/api`](../api/)). +kpt consists of three Go modules that are released together with **one locked version**: + +| Module | Path | Git tag | +|---|---|---| +| API | [`github.com/kptdev/kpt/api`](../api/) | `api/v1.2.3` | +| Root library | `github.com/kptdev/kpt` | `v1.2.3` | +| CLI | [`github.com/kptdev/kpt/cli`](../cli/) | `cli/v1.2.3` | + +The three tags point at different commits, because each module requires the previous one: +the root `go.mod` requires `api/v1.2.3` and `cli/go.mod` requires `v1.2.3` and `api/v1.2.3`. +Consumers pin modules with `go get github.com/kptdev/kpt/api@v1.2.3`; the `api/` and `cli/` prefixes only +exist on the git tags (see [Go modules: VCS version](https://go.dev/ref/mod#vcs-version)). + +## Creating a release + +Run the [kpt multimodule release](../.github/workflows/release.yml) workflow (Actions, "Run workflow", from `main`). Releases are +always made from `main`; the workflow refuses to run from any other ref. + +| Input | Description | +|---|---| +| `version` | New version, for example `v1.2.3` or `v1.2.3-pre.1`. Must be valid semver and newer than **all** existing `v*`, `api/v*` and `cli/v*` tags. | +| `dry_run` | Run everything locally in the runner, but push and publish nothing. Use it to try a release. | + +The workflow: + +1. Validates the version (semver, none of the three tags exist, newer than every existing release). +2. Fails if any `go.mod` has a `replace` directive, or requires a kpt module at a pseudo-version + (for example `v1.1.1-0.20260101000000-abcdef123456`). Pseudo-versions of other modules are fine. +3. Runs `make all` and `make test-docker` on `main`. +4. Tags `api/v1.2.3`, bumps the api requirement in the root `go.mod` and commits, tags `v1.2.3`, bumps the kpt and api + requirements in `cli/go.mod` and commits, tags `cli/v1.2.3`. The checks of step 2 run again on the result and the CLI is built. +5. Builds the CLI archives, Linux packages and checksums with GoReleaser ([`release/tag/goreleaser.yaml`](tag/goreleaser.yaml)). +6. Generates the release notes and stages the release assets, and prints both in the log and the job summary (also in dry + runs). This happens before anything is pushed. +7. Pushes `main` and the three tags in a single atomic push. +8. Creates the GitHub release **named `v1.2.3`, attached to the `cli/v1.2.3` tag**, with all artifacts. + Versions with a pre-release suffix are marked as pre-releases. +9. Creating the release triggers the [kpt release provenance](../.github/workflows/release-provenance.yml) workflow, which hashes + the published assets and uploads SLSA provenance to the release. The recorded revision is the commit of the `cli/v1.2.3` tag. + The provenance therefore attests the assets as they were published, not the run that built them. + +Nothing is pushed before the build and tests have succeeded. The steps are implemented in +[`scripts/multimodule-release/`](../scripts/multimodule-release/) (usage is documented in the header of `release.sh`). + +### Requirements + +- The kptdev-ci-bot GitHub App, which must be allowed to push to the (protected) `main` branch and to create tags and releases. + The workflow creates a short-lived token from the `CI_BOT_APP_ID` and `CI_BOT_PRIVATE_KEY` secrets right before it pushes. The + default `GITHUB_TOKEN` is not sufficient for protected branches. +- A GitHub environment named `release` that also contains the `CI_BOT_APP_ID` and `CI_BOT_PRIVATE_KEY` secrets (an environment + secret takes precedence over the organization secret of the same name). The environment should only allow deployments from + `main` and require approval from a maintainer, so the run waits for approval (dry runs too) before it can read the secrets. + Without the copies in the environment, the organization secrets are readable by any workflow in the repository, and the + environment would only add the approval step. +- `main` must not receive other commits while the workflow runs. If it does, the atomic push is rejected and nothing is published; + run the workflow again. -The CLI module depends on the root library, so the library tag has to exist before the CLI module can require that version. A paired release is two commits and two tags. Version numbers can match (`v1.2.3` and `cli/v1.2.3`); they still point at different commits. - -When `api/` changed, tag that module first and bump the root `go.mod` before tagging the library. - -## Root library (`github.com/kptdev/kpt`) - -Pushing a tag such as `v1.2.3` publishes the root module. Consumers pin it with `go get github.com/kptdev/kpt@v1.2.3`. That tag does not build CLI binaries. - -[.github/workflows/release.yml](../.github/workflows/release.yml) checks that the root `go.mod` has no `replace` directives and runs `make lib`. - -## CLI (`github.com/kptdev/kpt/cli`) - -After the root tag exists: - -1. In [`cli/go.mod`](../cli/go.mod), set `require github.com/kptdev/kpt` to that version (and the API module to the version this release should use). -2. Remove any `replace` directives. The CLI workflow fails if one is still present. -3. Run `go mod tidy` in `cli/`. -4. Commit that change, then push a tag `cli/v1.2.3` (same version number as the library tag when this is a paired release). Pre-releases use the same suffix, for example `cli/v1.2.3-beta.1`. - -[.github/workflows/release-cli.yml](../.github/workflows/release-cli.yml) runs tests, GoReleaser, container images, and provenance. The workflow passes the tag with the `cli/` prefix removed, so image tags and archive filenames stay `v1.2.3` / `1.2.3`. The GitHub Release is attached to the git tag, so download URLs look like: - -```text -https://github.com/kptdev/kpt/releases/download/cli/v1.2.3/kpt_linux_amd64-1.2.3.tar.gz -``` - -`go install github.com/kptdev/kpt/cli@v1.2.3` uses that `cli/v1.2.3` tag. +### Release notes -## kpt API module (`github.com/kptdev/kpt/api`) +The release notes are the GitHub generated notes for the whole repository since the previous `v*` release, followed by the +changes scoped to `api/` and `cli/` since their previous tags (the highest earlier tag with that prefix). The range ends at the +`main`, so the notes can be generated before the new tags are pushed. GoReleaser's changelog is disabled, because the open-source +version cannot scope changelogs to a module (no `monorepo` support). -The [`api/`](../api/) directory is its own Go module. Consumers pin it with `go get`, for example: +[`scripts/generate-folder-release-notes.sh`](../scripts/generate-folder-release-notes.sh) generates the folder scoped notes. It +calls the GitHub Release Notes API, then keeps only bullets whose PRs also appear in `git log` for the folder: ```shell -go get github.com/kptdev/kpt/api@v1.0.0 +scripts/generate-folder-release-notes.sh --folder api --new-tag v1.2.3 ``` -That `@v1.0.0` form is the **module version**; the corresponding **git tag** in this repo is **`api/v1.0.0`**. - -Tags must use the **`api/`** prefix so the version matches the module subdirectory (see [Go modules: VCS version](https://go.dev/ref/mod#vcs-version)). +Prerequisites: `gh` (authenticated to this repository) and a clone with tags fetched (`git fetch --tags`). -### Release notes +### Download URLs -GitHub's built-in "Generate release notes" includes PRs for the whole repository. For an API release, generate notes scoped to `api/` instead: +Because the release is attached to the CLI tag, URLs look like: -```shell -scripts/generate-folder-release-notes.sh --folder api --new-tag v1.2.3 +```text +https://github.com/kptdev/kpt/releases/download/cli/v1.2.3/kpt_linux_amd64-1.2.3.tar.gz ``` -That calls the GitHub Release Notes API, then keeps only bullets whose PRs also appear in `git log` for `api/` between the previous `api/v*` semver tag and `HEAD`. -Pass `--previous-tag` to pick a different start (version or full tag, for example `v1.2.2` or `api/v1.2.2`). -Use `-o FILE` to write the notes, and `--attribution` to prepend a note that they are folder-scoped. +`go install github.com/kptdev/kpt/cli@v1.2.3` uses the `cli/v1.2.3` tag. -Prerequisites: `gh` (authenticated to this repository) and a clone with tags fetched (`git fetch --tags`). +## When something fails -### What runs in CI +- Before the push (validation, checks, tests, build): nothing was published. Fix the problem and run the workflow again with the same version. +- The provenance failed: re-run the failed "kpt release provenance" workflow run (Actions, "Re-run failed jobs"). +- After the push (release creation failed): the tags exist and **must not be reused**. Either create the missing + release manually from the `cli/v1.2.3` tag, or delete the three tags and the bump commits and run again. Do not delete tags + that were already fetched by the Go module proxy; release a new version instead. -When you push a tag that matches **`api/v[0-9]+.[0-9]+.[0-9]+*`** (for example `api/v1.2.3`), [.github/workflows/release-api.yml](../.github/workflows/release-api.yml) runs: it uses the Go version from [`api/go.mod`](../api/go.mod) and runs **`make api`**. +## Local development -### Monorepo +`api/` and `cli/` are nested modules, so a tag for one module does not publish the others. A module zip excludes nested modules. +Local development can use a gitignored `go.work` (`make work`) so builds see the sibling modules without committed `replace` +directives. -`api/` and `cli/` are nested modules, so a tag for one module does not publish the others. A module zip excludes nested modules. Local development can use a gitignored `go.work` (`make work`) so builds see the sibling modules without committed `replace` directives. +The release scripts have unit tests (`scripts/multimodule-release/lib/test-*.sh`) that run in CI. Run them with `make test-scripts`. diff --git a/release/tag/goreleaser.yaml b/release/tag/goreleaser.yaml index 5917a84668..5938e23672 100644 --- a/release/tag/goreleaser.yaml +++ b/release/tag/goreleaser.yaml @@ -13,21 +13,24 @@ # limitations under the License. # This defines the build for goreleaser (https://goreleaser.com/). It is -# executed through a Github Action that is triggered by new tags being created -# in the kpt repo. +# executed by the multimodule release workflow (.github/workflows/release.yml), +# which publishes the GitHub release itself, so GoReleaser is run with +# --skip=publish and only builds and packages the artifacts. # As kpt needs to be compiled with CGO, we cannot simply just provide a simple # matrix of GOOS and GOARCH combinations, but instead, we'd need to define separate # steps for each targetted OS and ARCH. This is because we need to specify the # platform specific C std library (libc) and cross-compiler to be used. # The CLI is released from tags like cli/v1.2.3. GoReleaser's monorepo.tag_prefix -# setting is not available in the open-source build, and it would treat that tag -# as the version string. +# setting is not available in the open-source build, and .Version would be "cli/v1.2.3" +# (which ends up in the package versions). The workflow therefore sets +# GORELEASER_CURRENT_TAG=v1.2.3, the root tag of the same release. version: 2 env: - CGO_ENABLED=0 - GO111MODULE=on -# All other tags besides cli/* must not be treated as the previous CLI release. +# Only matters when GoReleaser detects tags itself (snapshot runs); the release +# workflow sets GORELEASER_CURRENT_TAG. git: ignore_tags: - "v*" @@ -86,9 +89,6 @@ archives: - darwin-arm64 - linux-amd64 - linux-arm64 - files: - - LICENSES* - - lib.zip* name_template: '{{ .ProjectName }}_{{ .Os }}_{{ .Arch }}-{{ trimprefix (base .Tag) "v" }}' - id: bin-only formats: binary @@ -121,19 +121,7 @@ nfpms: file_name_template: '{{ .ProjectName }}_{{ .Os }}_{{ .Arch }}-{{ trimprefix (base .Tag) "v" }}' checksum: name_template: "checksums.txt" +# The release notes and the GitHub release are created by the release workflow +# (the open-source build cannot scope a changelog to a module). changelog: - sort: asc - filters: - exclude: - - "(?i)^docs:" - - "(?i)^test:" - - "(?i)^regenerate docs" - - Merge pull request - - Merge branch -release: - github: - owner: kptdev - name: kpt - draft: false - prerelease: auto - + disable: true diff --git a/scripts/multimodule-release/lib/assets.sh b/scripts/multimodule-release/lib/assets.sh new file mode 100644 index 0000000000..e98a1bcc1a --- /dev/null +++ b/scripts/multimodule-release/lib/assets.sh @@ -0,0 +1,36 @@ +#!/usr/bin/env bash +# Copyright 2026 The kpt Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# Release asset staging. Sourced by release.sh, do not execute directly. + +# --- Subcommand: assets --- +# Copies everything GoReleaser built (dist/artifacts.json) that belongs on the +# GitHub release into OUTDIR, under the file names it would have uploaded: +# archives, linux packages, checksums and the plain binaries as kpt_OS_ARCH. +cmd_assets() { + local dist="$1" outdir="$2" + local artifacts="${dist}/artifacts.json" + [[ -f "$artifacts" ]] || fatal "${artifacts} not found" + mkdir -p "$outdir" + + local path + while IFS= read -r path; do + cp "$path" "$outdir/" + done < <(jq -r '.[] | select(.type == "Archive" or .type == "Linux Package" or .type == "Checksum") | .path' "$artifacts") + + while IFS=$'\t' read -r path os arch; do + cp "$path" "${outdir}/kpt_${os}_${arch}" + done < <(jq -r '[.[] | select(.type == "Binary")] | unique_by(.path)[] | [.path, .goos, .goarch] | @tsv' "$artifacts") + log "Staged $(find "$outdir" -type f | wc -l) release assets in ${outdir}" +} diff --git a/scripts/multimodule-release/lib/common.sh b/scripts/multimodule-release/lib/common.sh new file mode 100644 index 0000000000..8852688df4 --- /dev/null +++ b/scripts/multimodule-release/lib/common.sh @@ -0,0 +1,32 @@ +#!/usr/bin/env bash +# Copyright 2026 The kpt Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Common helpers. Sourced by release.sh, do not execute directly. + +# Modules released together: directory of the go.mod and the tag prefix. +# The root module is tagged without a prefix. +# shellcheck disable=SC2034 # used by the scripts sourcing this file +MODULES_API_DIR="api" +MODULES_CLI_DIR="cli" +API_MODULE="github.com/kptdev/kpt/api" +ROOT_MODULE="github.com/kptdev/kpt" + +log() { echo "[INFO] $*" >&2; } +fatal() { echo "[ERR] $*" >&2; exit 1; } + +# Lists tags of the remote (names only) so that unfetched tags are also seen. +remote_tags() { + git ls-remote --tags --refs origin | sed 's#.*refs/tags/##' +} diff --git a/scripts/multimodule-release/lib/notes.sh b/scripts/multimodule-release/lib/notes.sh new file mode 100644 index 0000000000..2381cacfbf --- /dev/null +++ b/scripts/multimodule-release/lib/notes.sh @@ -0,0 +1,52 @@ +#!/usr/bin/env bash +# Copyright 2026 The kpt Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# Release notes. Sourced by release.sh, do not execute directly. +# Requires gh (authenticated via GH_TOKEN) and the previous release tags on the remote. + +# --- Subcommand: notes --- +# The notes consist of the repository wide GitHub generated notes, followed by +# the changes scoped to the api/ and cli/ modules. The previous release of +# each is the highest earlier tag with the matching prefix. +# The range ends at the branch, not the new tags, so the notes also work before +# the tags are pushed (dry run). The bump commits have no PR and are ignored. +cmd_notes() { + local version="v${1#v}" branch="$2" outfile="$3" + local repo="${GITHUB_REPOSITORY:-kptdev/kpt}" + local tags + tags="$(remote_tags | grep -Fvx -e "$version" -e "api/${version}" -e "cli/${version}")" + + local prev_root + prev_root="$(latest_semver_tag "" <<< "$tags")" + + { + if [[ -n "$prev_root" ]]; then + gh api "repos/${repo}/releases/generate-notes" \ + -f tag_name="$version" -f previous_tag_name="$prev_root" -f target_commitish="$branch" --jq .body + else + gh api "repos/${repo}/releases/generate-notes" \ + -f tag_name="$version" -f target_commitish="$branch" --jq .body + fi + + local module prev + for module in "$MODULES_API_DIR" "$MODULES_CLI_DIR"; do + prev="$(latest_semver_tag "${module}/" <<< "$tags")" + [[ -n "$prev" ]] || continue + printf '\n## Changes in `%s/`\n\n' "$module" + GITHUB_REPOSITORY="$repo" "${REPO_ROOT}/scripts/generate-folder-release-notes.sh" \ + --folder "$module" --previous-tag "$prev" --new-tag "$version" --ref "$branch" \ + | sed '/^## What.s Changed$/d; /^\*\*Full Changelog/d' + done + } > "$outfile" +} diff --git a/scripts/multimodule-release/lib/semver.sh b/scripts/multimodule-release/lib/semver.sh new file mode 100644 index 0000000000..0d6b71db19 --- /dev/null +++ b/scripts/multimodule-release/lib/semver.sh @@ -0,0 +1,89 @@ +#!/usr/bin/env bash +# Copyright 2026 The kpt Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Strict semantic version handling. Sourced by release.sh, do not execute directly. + +SEMVER_RE='^v?(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-((0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(\.(0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?$' + +# is_semver VERSION: succeeds for MAJOR.MINOR.PATCH[-PRERELEASE] with optional +# "v" prefix. Build metadata is not allowed. +is_semver() { + [[ "$1" =~ $SEMVER_RE ]] +} + +# semver_cmp A B: prints -1, 0 or 1 following semver precedence rules. +semver_cmp() { + local a="$1" b="$2" + [[ "$a" =~ $SEMVER_RE ]] || fatal "invalid version: $a" + local a_core=("${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}" "${BASH_REMATCH[3]}") a_pre="${BASH_REMATCH[5]}" + [[ "$b" =~ $SEMVER_RE ]] || fatal "invalid version: $b" + local b_core=("${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}" "${BASH_REMATCH[3]}") b_pre="${BASH_REMATCH[5]}" + + local i + for i in 0 1 2; do + if ((a_core[i] > b_core[i])); then echo 1; return; fi + if ((a_core[i] < b_core[i])); then echo -1; return; fi + done + + # A version without a prerelease is newer than one with a prerelease. + if [[ -z "$a_pre" && -z "$b_pre" ]]; then echo 0; return; fi + if [[ -z "$a_pre" ]]; then echo 1; return; fi + if [[ -z "$b_pre" ]]; then echo -1; return; fi + + local a_ids b_ids + IFS='.' read -r -a a_ids <<< "$a_pre" + IFS='.' read -r -a b_ids <<< "$b_pre" + local n=${#a_ids[@]} + ((${#b_ids[@]} < n)) && n=${#b_ids[@]} + for ((i = 0; i < n; i++)); do + local x="${a_ids[i]}" y="${b_ids[i]}" + if [[ "$x" == "$y" ]]; then continue; fi + local x_num=0 y_num=0 + [[ "$x" =~ ^[0-9]+$ ]] && x_num=1 + [[ "$y" =~ ^[0-9]+$ ]] && y_num=1 + if ((x_num && y_num)); then + if ((x > y)); then echo 1; else echo -1; fi + elif ((x_num)); then + echo -1 # numeric identifiers are lower than alphanumeric ones + elif ((y_num)); then + echo 1 + elif [[ "$x" > "$y" ]]; then + echo 1 + else + echo -1 + fi + return + done + # All shared identifiers are equal: the longer prerelease is newer. + if ((${#a_ids[@]} > ${#b_ids[@]})); then echo 1 + elif ((${#a_ids[@]} < ${#b_ids[@]})); then echo -1 + else echo 0; fi +} + +# latest_semver_tag PREFIX: reads tag names on stdin and prints the highest +# one that is PREFIX followed by a semantic version (PREFIX is "" or "api/"). +latest_semver_tag() { + local prefix="$1" tag best="" + while IFS= read -r tag; do + [[ "$tag" == "$prefix"* ]] || continue + local ver="${tag#"$prefix"}" + [[ "$ver" == v* ]] || continue + is_semver "$ver" || continue + if [[ -z "$best" || "$(semver_cmp "$ver" "${best#"$prefix"}")" == 1 ]]; then + best="$tag" + fi + done + echo "$best" +} diff --git a/scripts/multimodule-release/lib/tag.sh b/scripts/multimodule-release/lib/tag.sh new file mode 100644 index 0000000000..18a749e406 --- /dev/null +++ b/scripts/multimodule-release/lib/tag.sh @@ -0,0 +1,78 @@ +#!/usr/bin/env bash +# Copyright 2026 The kpt Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# Tagging, bump commits and push. Sourced by release.sh, do not execute directly. + +# Runs a go command so that the new kpt tags, which only exist locally yet, resolve: +# the kpt repository URL is redirected to the local clone, and proxy and checksum +# database are bypassed for the kpt modules only. +with_local_kpt() { + GIT_CONFIG_COUNT=1 \ + GIT_CONFIG_KEY_0="url.file://${REPO_ROOT}/.git.insteadOf" \ + GIT_CONFIG_VALUE_0="https://github.com/kptdev/kpt" \ + GONOPROXY="github.com/kptdev/kpt" \ + GONOSUMDB="github.com/kptdev/kpt" \ + GOFLAGS=-mod=mod \ + "$@" +} + +# bump_module DIR COMMIT_MESSAGE MODULE@VERSION... +bump_module() { + local dir="$1" message="$2" + shift 2 + local req + for req in "$@"; do + (cd "$dir" && go mod edit -require="$req") + done + (cd "$dir" && with_local_kpt go mod tidy) + git add "${dir}/go.mod" "${dir}/go.sum" + git diff --cached --quiet && fatal "${dir}/go.mod did not change when bumping to ${*}" + git commit -q -s -m "$message" +} + +# --- Subcommand: tag --- +cmd_tag() { + local version="$1" + is_semver "$version" || fatal "invalid version: $version" + version="v${version#v}" + + git diff --quiet HEAD || fatal "Working tree has uncommitted changes to tracked files" + log "Tagging ${API_MODULE} as api/${version}" + git tag -a "api/${version}" -m "api ${version}" + + log "Updating the api requirement of the root module" + bump_module . "Release ${version}: update api module to ${version}" "${API_MODULE}@${version}" + git tag -a "${version}" -m "${version}" + + log "Updating the kpt and api requirements of the cli module" + bump_module "$MODULES_CLI_DIR" "Release ${version}: update kpt and api modules to ${version}" \ + "${ROOT_MODULE}@${version}" "${API_MODULE}@${version}" + git tag -a "cli/${version}" -m "cli ${version}" + + # The workflow checks afterwards that everything is pinned to tagged versions. + (cd "$MODULES_CLI_DIR" && CGO_ENABLED=0 with_local_kpt go build ./...) + log "Created tags api/${version}, ${version} and cli/${version}" +} + +# --- Subcommand: push --- +cmd_push() { + local version="v${1#v}" branch="$2" + local refs=("HEAD:refs/heads/${branch}" + "refs/tags/api/${version}" "refs/tags/${version}" "refs/tags/cli/${version}") + if [[ "${DRY_RUN:-false}" == "true" ]]; then + log "DRY_RUN: would run: git push --atomic origin ${refs[*]}" + return + fi + git push --atomic origin "${refs[@]}" +} diff --git a/scripts/multimodule-release/lib/test-assets.sh b/scripts/multimodule-release/lib/test-assets.sh new file mode 100755 index 0000000000..237b99e8ee --- /dev/null +++ b/scripts/multimodule-release/lib/test-assets.sh @@ -0,0 +1,52 @@ +#!/usr/bin/env bash +# Copyright 2026 The kpt Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Tests for the assets subcommand. + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +source "${SCRIPT_DIR}/testing.sh" +setup_tmp + +mkdir -p "${TMP}/dist/linux-amd64_linux_amd64_v1" "${TMP}/dist/darwin-arm64_darwin_arm64_v8.0" +WORK="$TMP" +cd "$TMP" || exit 1 +mkdir -p scripts +cp -r "$RELEASE_SCRIPTS_DIR" scripts/multimodule-release +for f in dist/kpt_linux_amd64-1.2.3.tar.gz dist/kpt_linux_amd64-1.2.3.deb dist/checksums.txt dist/metadata.json \ + dist/linux-amd64_linux_amd64_v1/kpt dist/darwin-arm64_darwin_arm64_v8.0/kpt; do + echo "$f" > "$f" +done +cat > dist/artifacts.json <<'JSON' +[ + {"name":"kpt_linux_amd64-1.2.3.tar.gz","path":"dist/kpt_linux_amd64-1.2.3.tar.gz","type":"Archive"}, + {"name":"kpt_linux_amd64-1.2.3.deb","path":"dist/kpt_linux_amd64-1.2.3.deb","type":"Linux Package"}, + {"name":"checksums.txt","path":"dist/checksums.txt","type":"Checksum"}, + {"name":"metadata.json","path":"dist/metadata.json","type":"Metadata"}, + {"name":"kpt","path":"dist/linux-amd64_linux_amd64_v1/kpt","type":"Binary","goos":"linux","goarch":"amd64"}, + {"name":"kpt","path":"dist/linux-amd64_linux_amd64_v1/kpt","type":"Binary","goos":"linux","goarch":"amd64"}, + {"name":"kpt","path":"dist/darwin-arm64_darwin_arm64_v8.0/kpt","type":"Binary","goos":"darwin","goarch":"arm64"} +] +JSON +git init -q -b main . >/dev/null +run_release assets dist out +assert_eq 0 "$RC" "assets succeeds: ${OUT}" +assert_eq "checksums.txt kpt_darwin_arm64 kpt_linux_amd64 kpt_linux_amd64-1.2.3.deb kpt_linux_amd64-1.2.3.tar.gz" \ + "$(ls out | tr '\n' ' ' | sed 's/ $//')" "release assets are staged with their upload names" +assert_eq "dist/linux-amd64_linux_amd64_v1/kpt" "$(cat out/kpt_linux_amd64)" "plain binary content is copied" + +run_release assets nonexistent out2 +assert_eq 1 "$RC" "missing artifacts.json is rejected" + +finish diff --git a/scripts/multimodule-release/lib/test-notes.sh b/scripts/multimodule-release/lib/test-notes.sh new file mode 100755 index 0000000000..50f478e3f9 --- /dev/null +++ b/scripts/multimodule-release/lib/test-notes.sh @@ -0,0 +1,112 @@ +#!/usr/bin/env bash +# Copyright 2026 The kpt Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Tests for the notes subcommand. +# +# Known history on top of v1.0.0, api/v1.0.0 and cli/v1.0.0 (PR numbers as in +# squash merge subjects): +# #12 touches api/ <- api/v1.0.1-pre.1 is tagged here +# #13 touches cli/ +# #15 touches api/ +# #14 touches the root +# Expected: api/ notes since api/v1.0.1-pre.1 have #15 only, cli/ notes since +# cli/v1.0.0 have #13 only. +# gh is stubbed: it returns notes listing all four PRs and records its arguments. + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +source "${SCRIPT_DIR}/testing.sh" +setup_tmp +make_fixture + +( + cd "$WORK" || exit 1 + echo a > api/a.txt && git add -A && git commit -q -m "feat api (#12)" + git tag api/v1.0.1-pre.1 + echo c > cli/c.txt && git add -A && git commit -q -m "feat cli (#13)" + echo b > api/b.txt && git add -A && git commit -q -m "fix api (#15)" + echo r > r.txt && git add -A && git commit -q -m "other (#14)" + git push -q origin main api/v1.0.1-pre.1 +) + +mkdir -p "${TMP}/bin" +cat > "${TMP}/bin/gh" <<'STUB' +#!/usr/bin/env bash +echo "$*" >> "${GH_STUB_LOG}" +cat <<'BODY' +## What's Changed +* feat api by @a in https://github.com/kptdev/kpt/pull/12 +* feat cli by @a in https://github.com/kptdev/kpt/pull/13 +* other by @a in https://github.com/kptdev/kpt/pull/14 +* fix api by @a in https://github.com/kptdev/kpt/pull/15 + +**Full Changelog**: https://github.com/kptdev/kpt/compare/v1.0.0...v1.1.0 +BODY +STUB +chmod +x "${TMP}/bin/gh" +export PATH="${TMP}/bin:${PATH}" +export GH_STUB_LOG="${TMP}/gh.log" + +section() { # NOTES MODULE: the lines of the "Changes in MODULE/" section + awk -v h="## Changes in \`$2/\`" '$0 == h {on=1; next} /^## /{on=0} on' <<< "$1" +} + +check_notes() { # LABEL: verifies ${TMP}/notes.md and the gh calls + local label="$1" notes calls + notes="$(cat "${TMP}/notes.md")" + calls="$(cat "$GH_STUB_LOG")" + + # Full notes: every PR, as returned for the previous root release. + assert_contains "$notes" "pull/14" "${label}: full notes contain the root PR" + assert_contains "$calls" "tag_name=v1.1.0 -f previous_tag_name=v1.0.0 -f target_commitish=main" \ + "${label}: full notes are requested since the previous root release" + + # Scoped notes: only PRs that touched the module since its previous tag. + assert_contains "$calls" "tag_name=api/v1.1.0 -f previous_tag_name=api/v1.0.1-pre.1 -f target_commitish=main" \ + "${label}: api notes are requested since the highest earlier api tag" + assert_contains "$calls" "tag_name=cli/v1.1.0 -f previous_tag_name=cli/v1.0.0 -f target_commitish=main" \ + "${label}: cli notes are requested since the previous cli tag" + + local api_notes cli_notes + api_notes="$(section "$notes" api)" + cli_notes="$(section "$notes" cli)" + assert_contains "$api_notes" "pull/15" "${label}: api section has the api PR after the previous api tag" + assert_not_contains "$api_notes" "pull/12" "${label}: api section has no PR from before the previous api tag" + assert_not_contains "$api_notes" "pull/13" "${label}: api section has no cli PR" + assert_not_contains "$api_notes" "pull/14" "${label}: api section has no root PR" + assert_contains "$cli_notes" "pull/13" "${label}: cli section has the cli PR" + assert_not_contains "$cli_notes" "pull/12" "${label}: cli section has no api PR" + assert_not_contains "$cli_notes" "pull/15" "${label}: cli section has no api PR" +} + +# Dry run: the new tags exist locally only (and the bump commits are not pushed). +run_release tag v1.1.0 +assert_eq 0 "$RC" "tag succeeds: ${OUT}" +: > "$GH_STUB_LOG" +run_release notes v1.1.0 main "${TMP}/notes.md" +assert_eq 0 "$RC" "notes succeed before the push: ${OUT}" +check_notes "before push" +cp "${TMP}/notes.md" "${TMP}/notes-before-push.md" + +# Real run: the same notes after the new tags were pushed. +run_release push v1.1.0 main +assert_eq 0 "$RC" "push succeeds: ${OUT}" +: > "$GH_STUB_LOG" +run_release notes v1.1.0 main "${TMP}/notes.md" +assert_eq 0 "$RC" "notes succeed after the push: ${OUT}" +check_notes "after push" +assert_eq "$(cat "${TMP}/notes-before-push.md")" "$(cat "${TMP}/notes.md")" \ + "notes are the same before and after pushing the tags" + +finish diff --git a/scripts/multimodule-release/lib/test-semver.sh b/scripts/multimodule-release/lib/test-semver.sh new file mode 100755 index 0000000000..1da169a267 --- /dev/null +++ b/scripts/multimodule-release/lib/test-semver.sh @@ -0,0 +1,62 @@ +#!/usr/bin/env bash +# Copyright 2026 The kpt Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Unit tests for semver.sh. + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +source "${SCRIPT_DIR}/testing.sh" +source "${SCRIPT_DIR}/common.sh" +source "${SCRIPT_DIR}/semver.sh" + +expect_cmp() { # A B WANT + assert_eq "$3" "$(semver_cmp "$1" "$2")" "semver_cmp $1 $2" +} +expect_valid() { # VERSION valid|invalid + local got=invalid + if is_semver "$1"; then got=valid; fi + assert_eq "$2" "$got" "is_semver '$1'" +} + +expect_cmp v1.0.0 v1.0.0 0 +expect_cmp v1.0.1 v1.0.0 1 +expect_cmp v1.10.0 v1.9.0 1 +expect_cmp v1.0.0 v1.0.0-pre.1 1 +expect_cmp v1.0.0-pre.1 v1.0.0 -1 +expect_cmp v1.0.2-pre.4 v1.0.2-pre.10 -1 +expect_cmp v1.0.0-alpha v1.0.0-alpha.1 -1 +expect_cmp v1.0.0-alpha.1 v1.0.0-alpha.beta -1 +expect_cmp v1.0.0-beta.2 v1.0.0-beta.11 -1 +expect_cmp v1.0.0-beta v1.0.0-alpha 1 +expect_cmp 1.1.1 v1.1.1-pre.2 1 +expect_cmp v1.0.0-beta.7 v1.0.0-beta.10 -1 + +expect_valid v1.2.3 valid +expect_valid 1.2.3 valid +expect_valid v1.2.3-pre.1 valid +expect_valid v10.20.30-rc.1 valid +expect_valid v1.2 invalid +expect_valid v01.2.3 invalid +expect_valid v1.2.3+meta invalid +expect_valid v1.2.3-01 invalid +expect_valid latest invalid +expect_valid "v1.2.3 " invalid + +tags=$'v1.0.2-pre.4\nv1.0.2-pre.10\nv1.0.1\napi/v1.1.1-pre.2\napi/v1.1.0\ncli/v1.0.2-pre.4\nporch/v9.0.0' +assert_eq v1.0.2-pre.10 "$(latest_semver_tag "" <<< "$tags")" "latest root tag" +assert_eq api/v1.1.1-pre.2 "$(latest_semver_tag "api/" <<< "$tags")" "latest api tag" +assert_eq cli/v1.0.2-pre.4 "$(latest_semver_tag "cli/" <<< "$tags")" "latest cli tag" +assert_eq "" "$(latest_semver_tag "other/" <<< "$tags")" "no tag for an unknown prefix" + +finish diff --git a/scripts/multimodule-release/lib/test-tag.sh b/scripts/multimodule-release/lib/test-tag.sh new file mode 100755 index 0000000000..27a4b3c2c8 --- /dev/null +++ b/scripts/multimodule-release/lib/test-tag.sh @@ -0,0 +1,73 @@ +#!/usr/bin/env bash +# Copyright 2026 The kpt Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Tests for the tag and push subcommands. + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +source "${SCRIPT_DIR}/testing.sh" +setup_tmp +make_fixture + +base="$(git -C "$WORK" rev-parse HEAD)" + +# A dirty working tree must be rejected before anything is created. +echo "// dirty" >> "${WORK}/kpt.go" +run_release tag v1.1.0 +assert_eq 1 "$RC" "dirty tree is rejected" +assert_eq "" "$(git -C "$WORK" tag -l 'api/v1.1.0')" "no tag created for a dirty tree" +git -C "$WORK" checkout -q kpt.go + +run_release tag v1.1.0 +assert_eq 0 "$RC" "tag succeeds: ${OUT}" + +api_commit="$(git -C "$WORK" rev-parse 'api/v1.1.0^{commit}')" +root_commit="$(git -C "$WORK" rev-parse 'v1.1.0^{commit}')" +cli_commit="$(git -C "$WORK" rev-parse 'cli/v1.1.0^{commit}')" +assert_eq "$base" "$api_commit" "api tag is on the unchanged commit" +assert_eq "$root_commit" "$(git -C "$WORK" rev-parse HEAD~1)" "root tag is on the first bump commit" +assert_eq "$cli_commit" "$(git -C "$WORK" rev-parse HEAD)" "cli tag is on HEAD" +assert_eq "$base" "$(git -C "$WORK" rev-parse HEAD~2)" "exactly two bump commits were added" + +root_mod="$(git -C "$WORK" show v1.1.0:go.mod)" +assert_contains "$root_mod" "github.com/kptdev/kpt/api v1.1.0" "root go.mod requires the new api" +cli_mod="$(git -C "$WORK" show cli/v1.1.0:cli/go.mod)" +assert_contains "$cli_mod" "github.com/kptdev/kpt v1.1.0" "cli go.mod requires the new root" +assert_contains "$cli_mod" "github.com/kptdev/kpt/api v1.1.0" "cli go.mod requires the new api" +assert_not_contains "$cli_mod" "replace" "cli go.mod has no replace directive" +assert_contains "$(git -C "$WORK" show cli/v1.1.0:cli/go.sum)" "github.com/kptdev/kpt v1.1.0 h1:" "cli go.sum has the root hash" +assert_contains "$(git -C "$WORK" log -1 --format=%B)" "Signed-off-by:" "bump commits are signed off" + +# Dry run pushes nothing. +DRY_RUN=true run_release push v1.1.0 main +assert_eq 0 "$RC" "dry run succeeds" +assert_eq "" "$(git -C "$ORIGIN" tag -l '*v1.1.0')" "dry run pushed no tags" +assert_eq "$base" "$(git -C "$ORIGIN" rev-parse main)" "dry run did not move the branch" + +# A moved remote branch must make the atomic push fail without pushing any tag. +other="${TMP}/other" +git clone -q "$ORIGIN" "$other" +(cd "$other" && echo x > x.txt && git add x.txt && git commit -q -m other && git push -q origin main) +run_release push v1.1.0 main +assert_eq 1 "$RC" "push to a moved branch is rejected" +assert_eq "" "$(git -C "$ORIGIN" tag -l '*v1.1.0')" "no tag was pushed when the push was rejected" + +# Once the local branch contains the remote commit again, the push goes through. +git -C "$WORK" pull -q --rebase origin main +run_release push v1.1.0 main +assert_eq 0 "$RC" "push after rebase succeeds: ${OUT}" +assert_eq "api/v1.1.0 cli/v1.1.0 v1.1.0" "$(git -C "$ORIGIN" tag -l '*v1.1.0' | sort | tr '\n' ' ' | sed 's/ $//')" "all three tags are pushed" +assert_eq "$(git -C "$WORK" rev-parse HEAD)" "$(git -C "$ORIGIN" rev-parse main)" "branch is pushed" + +finish diff --git a/scripts/multimodule-release/lib/test-validate.sh b/scripts/multimodule-release/lib/test-validate.sh new file mode 100755 index 0000000000..34929dbd87 --- /dev/null +++ b/scripts/multimodule-release/lib/test-validate.sh @@ -0,0 +1,65 @@ +#!/usr/bin/env bash +# Copyright 2026 The kpt Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Tests for the validate subcommand. + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +source "${SCRIPT_DIR}/testing.sh" +setup_tmp +make_fixture + +run_release validate 1.1.0 main +assert_eq 0 "$RC" "newer version is accepted" +assert_contains "$OUT" "v1.1.0" "version is printed with v prefix" + +run_release validate v1.1.0-pre.1 main +assert_eq 0 "$RC" "prerelease newer than the last release is accepted" + +(cd "$WORK" && git tag v2.0.0-pre.1 && git push -q origin v2.0.0-pre.1) + +run_release validate v1.9.0 main +assert_eq 1 "$RC" "version older than a prerelease tag of a higher version is rejected" + +run_release validate v2.0.0 main +assert_eq 0 "$RC" "release is newer than its prerelease tag" + +run_release validate v2.0.0-pre.2 main +assert_eq 0 "$RC" "newer prerelease is accepted" + +run_release validate v2.0.0-pre.1 main +assert_eq 1 "$RC" "existing tag is rejected" +assert_contains "$OUT" "already exists" "existing tag message" + +run_release validate v1.0.5 main +assert_eq 1 "$RC" "older version is rejected" +assert_contains "$OUT" "not newer" "older version message" + +run_release validate latest main +assert_eq 1 "$RC" "non-semver is rejected" + +run_release validate v2.1.0+build main +assert_eq 1 "$RC" "build metadata is rejected" + +run_release validate v2.1.0 nope +assert_eq 1 "$RC" "missing branch is rejected" +assert_contains "$OUT" "not found" "missing branch message" + +# Only one module tag being ahead must also block the version. +(cd "$WORK" && git tag api/v3.0.0 && git push -q origin api/v3.0.0) +run_release validate v2.5.0 main +assert_eq 1 "$RC" "version older than an api tag is rejected" +assert_contains "$OUT" "api/v3.0.0" "blocking tag is named" + +finish diff --git a/scripts/multimodule-release/lib/testing.sh b/scripts/multimodule-release/lib/testing.sh new file mode 100644 index 0000000000..e907166717 --- /dev/null +++ b/scripts/multimodule-release/lib/testing.sh @@ -0,0 +1,95 @@ +#!/usr/bin/env bash +# Copyright 2026 The kpt Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# Minimal test helpers and a fake repository fixture for the release script +# tests. Sourced by the test-*.sh files, do not execute directly. + +set -euo pipefail + +TESTING_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +RELEASE_SCRIPTS_DIR="$(cd "${TESTING_DIR}/.." && pwd)" +SCRIPTS_DIR="$(cd "${RELEASE_SCRIPTS_DIR}/.." && pwd)" + +FAILURES=0 +TESTS=0 + +pass() { TESTS=$((TESTS + 1)); } +fail() { TESTS=$((TESTS + 1)); FAILURES=$((FAILURES + 1)); echo "FAIL: $*"; } + +assert_eq() { # WANT GOT MESSAGE + if [[ "$1" == "$2" ]]; then pass; else fail "$3: want '$1', got '$2'"; fi +} +assert_contains() { # HAYSTACK NEEDLE MESSAGE + if [[ "$1" == *"$2"* ]]; then pass; else fail "$3: '$2' not found in: $1"; fi +} +assert_not_contains() { # HAYSTACK NEEDLE MESSAGE + if [[ "$1" != *"$2"* ]]; then pass; else fail "$3: '$2' unexpectedly found in: $1"; fi +} + +finish() { + if ((FAILURES > 0)); then + echo "${FAILURES} of ${TESTS} assertions failed" + exit 1 + fi + echo "All ${TESTS} assertions passed" +} + +# setup_tmp: creates a temp dir in TMP, isolated from the user's git config and +# Go module cache (the tests create fake kpt modules that must never end up in +# the real cache), and removes it on exit. +setup_tmp() { + TMP="$(mktemp -d)" + trap 'chmod -R u+w "$TMP" 2>/dev/null; rm -rf "$TMP"' EXIT + export GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null + export GIT_AUTHOR_NAME=Test GIT_AUTHOR_EMAIL=test@example.com + export GIT_COMMITTER_NAME=Test GIT_COMMITTER_EMAIL=test@example.com + export GOMODCACHE="${TMP}/gomodcache" GOTOOLCHAIN=local GOFLAGS= +} + +# run_release ARGS...: runs release.sh in WORK, sets OUT (stdout+stderr) and RC. +run_release() { + set +e + OUT="$(cd "$WORK" && scripts/multimodule-release/release.sh "$@" 2>&1)" + RC=$? + set -e +} + +# make_fixture: creates ORIGIN (bare) and WORK (clone) containing small fake api, +# root and cli modules with the real module paths and the release scripts. The +# commit is tagged and pushed as v1.0.0, api/v1.0.0 and cli/v1.0.0 on branch main. +make_fixture() { + ORIGIN="${TMP}/origin.git" + WORK="${TMP}/work" + git init -q --bare -b main "$ORIGIN" + git init -q -b main "$WORK" + ( + cd "$WORK" || exit 1 + mkdir -p api cli scripts + cp -r "$RELEASE_SCRIPTS_DIR" scripts/multimodule-release + cp "${SCRIPTS_DIR}/generate-folder-release-notes.sh" scripts/ + + printf 'module github.com/kptdev/kpt/api\n\ngo 1.21\n' > api/go.mod + printf 'package api\n' > api/api.go + printf 'module github.com/kptdev/kpt\n\ngo 1.21\n\nrequire github.com/kptdev/kpt/api v1.0.0\n' > go.mod + printf 'package kpt\n\nimport _ "github.com/kptdev/kpt/api"\n' > kpt.go + printf 'module github.com/kptdev/kpt/cli\n\ngo 1.21\n\nrequire (\n\tgithub.com/kptdev/kpt v1.0.0\n\tgithub.com/kptdev/kpt/api v1.0.0\n)\n' > cli/go.mod + printf 'package main\n\nimport (\n\t_ "github.com/kptdev/kpt"\n\t_ "github.com/kptdev/kpt/api"\n)\n\nfunc main() {}\n' > cli/main.go + + git add -A + git commit -q -m "initial" + git tag v1.0.0 && git tag api/v1.0.0 && git tag cli/v1.0.0 + git remote add origin "$ORIGIN" + git push -q origin main v1.0.0 api/v1.0.0 cli/v1.0.0 + ) +} diff --git a/scripts/multimodule-release/lib/validate.sh b/scripts/multimodule-release/lib/validate.sh new file mode 100644 index 0000000000..8dd2dfc8df --- /dev/null +++ b/scripts/multimodule-release/lib/validate.sh @@ -0,0 +1,48 @@ +#!/usr/bin/env bash +# Copyright 2026 The kpt Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# Input validation. Sourced by release.sh, do not execute directly. + +# --- Subcommand: validate --- +# Prints the normalized version (with "v" prefix) on stdout. +cmd_validate() { + local version="$1" branch="$2" + + is_semver "$version" || fatal "'${version}' is not a valid semantic version (expected MAJOR.MINOR.PATCH[-PRERELEASE])" + version="v${version#v}" + + git ls-remote --exit-code --heads origin "$branch" >/dev/null 2>&1 \ + || fatal "Branch '${branch}' not found in remote 'origin'" + + local tags tag + tags="$(remote_tags)" + for tag in "${version}" "api/${version}" "cli/${version}"; do + if grep -Fqx -- "$tag" <<< "$tags"; then + fatal "Tag '${tag}' already exists" + fi + done + + # The new version must be newer than every existing release of every module. + local prefix latest + for prefix in "" "api/" "cli/"; do + latest="$(latest_semver_tag "$prefix" <<< "$tags")" + [[ -n "$latest" ]] || continue + if [[ "$(semver_cmp "$version" "${latest#"$prefix"}")" != 1 ]]; then + fatal "Version ${version} is not newer than existing tag '${latest}'" + fi + done + + log "Version ${version} is valid and newer than all existing releases" + echo "$version" +} diff --git a/scripts/multimodule-release/release.sh b/scripts/multimodule-release/release.sh new file mode 100755 index 0000000000..da7c3c864e --- /dev/null +++ b/scripts/multimodule-release/release.sh @@ -0,0 +1,64 @@ +#!/usr/bin/env bash +# Copyright 2026 The kpt Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Multimodule release utility: releases the api, root and cli modules with one +# locked version. See release/README.md for the full process. +# +# Usage: release.sh [args] +# +# Subcommands: +# validate VERSION BRANCH Validate the version/branch and print the normalized version +# tag VERSION Create the bump commits and the api/, root and cli/ tags locally +# push VERSION BRANCH Atomically push the branch and the three tags (DRY_RUN=true skips) +# notes VERSION BRANCH OUTFILE Write the combined release notes (new tags need not be pushed) +# assets DIST OUTDIR Stage the GoReleaser artifacts to attach to the release +# +# Environment: +# DRY_RUN When "true", `push` does not push anything +# GITHUB_REPOSITORY Repository for release notes (default: kptdev/kpt) + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)" + +source "${SCRIPT_DIR}/lib/common.sh" +source "${SCRIPT_DIR}/lib/semver.sh" +source "${SCRIPT_DIR}/lib/validate.sh" +source "${SCRIPT_DIR}/lib/tag.sh" +source "${SCRIPT_DIR}/lib/notes.sh" +source "${SCRIPT_DIR}/lib/assets.sh" + +usage() { + sed -n '/^# Usage:/,/^$/p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//' + exit 2 +} + +main() { + [[ $# -ge 1 ]] || usage + local cmd="$1" + shift + cd "$REPO_ROOT" + case "$cmd" in + validate) [[ $# -eq 2 ]] || usage; cmd_validate "$@" ;; + tag) [[ $# -eq 1 ]] || usage; cmd_tag "$@" ;; + push) [[ $# -eq 2 ]] || usage; cmd_push "$@" ;; + notes) [[ $# -eq 3 ]] || usage; cmd_notes "$@" ;; + assets) [[ $# -eq 2 ]] || usage; cmd_assets "$@" ;; + *) usage ;; + esac +} + +main "$@"