ci(release): add reviewed version PRs and manual publication

Create Release Please PRs, synchronize release metadata, and test the exact merge commit before tagging and building an unpublished draft.

Verify release artifacts before manual publication and keep Homebrew and Docker distribution tied to the approved version. Document explicit version overrides and squash-merge behavior in the release skills and runbook.

Validation: make check, 12 release helper tests, actionlint, and an isolated six-platform GoReleaser build with artifact verification.
This commit is contained in:
Willie
2026-10-02 01:53:47 +08:00
parent ffabe1a86a
commit 1fe668ec54
16 changed files with 869 additions and 391 deletions
+26
View File
@@ -0,0 +1,26 @@
{
"$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
"release-type": "go",
"include-component-in-tag": false,
"bump-minor-pre-major": true,
"bump-patch-for-minor-pre-major": false,
"draft": true,
"force-tag-creation": true,
"bootstrap-sha": "bcea0b0fc97515be5ef3a7ccb49626f114ccf73f",
"changelog-sections": [
{ "type": "feat", "section": "New Features" },
{ "type": "fix", "section": "Bug Fixes" },
{ "type": "perf", "section": "Performance" },
{ "type": "revert", "section": "Reverts" },
{ "type": "docs", "hidden": true },
{ "type": "chore", "hidden": true },
{ "type": "test", "hidden": true },
{ "type": "ci", "hidden": true },
{ "type": "build", "hidden": true },
{ "type": "style", "hidden": true },
{ "type": "refactor", "hidden": true }
],
"packages": {
".": {}
}
}
+3
View File
@@ -0,0 +1,3 @@
{
".": "0.23.1"
}
+46 -7
View File
@@ -1,9 +1,26 @@
name: Docker Publish
on:
push:
tags:
- "v*"
release:
types: [published]
workflow_call:
inputs:
tag:
type: string
required: true
sha:
type: string
required: true
workflow_dispatch:
inputs:
tag:
description: Published release tag to redistribute (e.g. v0.24.0)
type: string
required: true
concurrency:
group: docker-publish
cancel-in-progress: false
permissions:
contents: read
@@ -25,6 +42,23 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@v4
with:
ref: refs/tags/${{ inputs.tag || github.event.release.tag_name }}
- name: Verify the published version and exact commit
id: version
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TAG: ${{ inputs.tag || github.event.release.tag_name }}
APPROVED_SHA: ${{ inputs.sha }}
run: |
CURRENT_SHA=$(git rev-parse HEAD)
VERSION=$(python3 scripts/release/release.py check --tag "$TAG" --sha "${APPROVED_SHA:-$CURRENT_SHA}")
test "$(gh release view "$TAG" --json isDraft --jq .isDraft)" = false
test "$(gh api "repos/$GITHUB_REPOSITORY/releases/latest" --jq .tag_name)" = "$TAG"
echo "version=$VERSION" >> "$GITHUB_OUTPUT"
echo "sha=$CURRENT_SHA" >> "$GITHUB_OUTPUT"
echo "short_sha=${CURRENT_SHA:0:7}" >> "$GITHUB_OUTPUT"
- name: Set up QEMU
uses: docker/setup-qemu-action@v3
@@ -45,9 +79,9 @@ jobs:
with:
images: ${{ env.REGISTRY }}/${{ github.repository }}${{ matrix.image_suffix }}
tags: |
type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}}
type=sha
type=semver,pattern={{version}},value=${{ inputs.tag || github.event.release.tag_name }}
type=semver,pattern={{major}}.{{minor}},value=${{ inputs.tag || github.event.release.tag_name }}
type=raw,value=sha-${{ steps.version.outputs.short_sha }}
- name: Build and push
uses: docker/build-push-action@v6
@@ -55,8 +89,13 @@ jobs:
context: .
file: ${{ matrix.dockerfile }}
platforms: linux/amd64,linux/arm64
build-args: |
VERSION=${{ steps.version.outputs.version }}
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
labels: |
${{ steps.meta.outputs.labels }}
org.opencontainers.image.version=${{ steps.version.outputs.version }}
org.opencontainers.image.revision=${{ steps.version.outputs.sha }}
cache-from: type=gha
cache-to: type=gha,mode=max
+97
View File
@@ -0,0 +1,97 @@
name: Publish Release
on:
workflow_dispatch:
inputs:
tag:
description: Verified draft to publish and distribute (e.g. v0.24.0)
type: string
required: true
concurrency:
group: publish-release
cancel-in-progress: false
permissions:
contents: read
jobs:
publish:
runs-on: ubuntu-latest
permissions:
contents: write
outputs:
sha: ${{ steps.verify.outputs.sha }}
steps:
- name: Check out the exact release tag
uses: actions/checkout@v4
with:
ref: refs/tags/${{ inputs.tag }}
fetch-depth: 0
- name: Verify release metadata, checksums and the packaged CLI
id: verify
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TAG: ${{ inputs.tag }}
run: |
VERSION=$(python3 scripts/release/release.py check --tag "$TAG")
gh api "repos/$GITHUB_REPOSITORY/releases/latest" --jq .tag_name > "$RUNNER_TEMP/latest-tag"
python3 - <<'PY'
import os
from pathlib import Path
from sys import path
path.insert(0, "scripts/release")
from release import VERSION
import re
latest = (Path(os.environ["RUNNER_TEMP"]) / "latest-tag").read_text().strip()
tag = os.environ["TAG"]
if not re.fullmatch("v" + VERSION, latest):
raise SystemExit("Latest published release must have a stable vX.Y.Z tag")
if tuple(map(int, latest[1:].split("."))) > tuple(map(int, tag[1:].split("."))):
raise SystemExit("Refusing to publish or redistribute an older version")
PY
gh release download "$TAG" --dir "$RUNNER_TEMP/release-assets"
python3 scripts/release/release.py verify-assets --tag "$TAG" --assets "$RUNNER_TEMP/release-assets"
echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
echo "version=$VERSION" >> "$GITHUB_OUTPUT"
- name: Publish the verified draft
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TAG: ${{ inputs.tag }}
run: |
if test "$(gh release view "$TAG" --json isDraft --jq .isDraft)" = true; then
gh release edit "$TAG" --draft=false --latest
fi
- name: Check out the Homebrew tap
uses: actions/checkout@v4
with:
repository: runkids/homebrew-tap
token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
path: homebrew-tap
- name: Publish the verified Homebrew formula
env:
VERSION: ${{ steps.verify.outputs.version }}
run: |
cp "$RUNNER_TEMP/release-assets/skillshare.rb" homebrew-tap/Formula/skillshare.rb
cd homebrew-tap
git add Formula/skillshare.rb
if ! git diff --cached --quiet; then
git -c user.name='github-actions[bot]' \
-c user.email='41898282+github-actions[bot]@users.noreply.github.com' \
commit -m "chore: release skillshare v$VERSION"
git push origin HEAD
fi
docker:
needs: publish
uses: ./.github/workflows/docker-publish.yml
permissions:
contents: read
packages: write
with:
tag: ${{ inputs.tag }}
sha: ${{ needs.publish.outputs.sha }}
+144
View File
@@ -0,0 +1,144 @@
name: Release Please
on:
push:
branches: [main]
workflow_dispatch:
concurrency:
group: release-please
cancel-in-progress: false
permissions:
contents: read
jobs:
prepare:
runs-on: ubuntu-latest
permissions:
contents: write
issues: write
pull-requests: write
outputs:
release_sha: ${{ steps.pending.outputs.sha }}
release_pr: ${{ steps.pending.outputs.number }}
steps:
- uses: actions/checkout@v4
- name: Find a merged release awaiting verification
id: pending
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
gh pr list --repo "$GITHUB_REPOSITORY" --base main --state merged \
--label 'autorelease: pending' --limit 2 --json number,mergeCommit > "$RUNNER_TEMP/pending.json"
python3 - <<'PY'
import json, os
from pathlib import Path
pending = json.loads((Path(os.environ["RUNNER_TEMP"]) / "pending.json").read_text())
if len(pending) > 1:
raise SystemExit("Resolve multiple pending releases before creating a tag")
if pending:
with open(os.environ["GITHUB_OUTPUT"], "a") as output:
output.write(f"sha={pending[0]['mergeCommit']['oid']}\nnumber={pending[0]['number']}\n")
PY
- name: Create or update the Release PR
id: release_pr
if: steps.pending.outputs.sha == ''
uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
with:
config-file: .github/release-please-config.json
manifest-file: .github/release-please-manifest.json
target-branch: main
skip-github-release: true
- name: Check out the Release PR
if: steps.release_pr.outputs.pr != ''
uses: actions/checkout@v4
with:
ref: ${{ fromJSON(steps.release_pr.outputs.pr).headBranchName }}
- name: Synchronize version and website changelog
if: steps.release_pr.outputs.pr != ''
run: |
python3 scripts/release/release.py sync
git add CHANGELOG.md website/src/pages/changelog.md skills/skillshare/SKILL.md
if ! git diff --cached --quiet; then
git -c user.name='github-actions[bot]' \
-c user.email='41898282+github-actions[bot]@users.noreply.github.com' \
commit -m 'chore(release): synchronize release metadata'
git push origin HEAD
fi
test:
needs: prepare
if: needs.prepare.outputs.release_sha != ''
uses: ./.github/workflows/test.yaml
with:
ref: ${{ needs.prepare.outputs.release_sha }}
tag:
needs: [prepare, test]
runs-on: ubuntu-latest
permissions:
contents: write
issues: write
pull-requests: write
outputs:
tag: ${{ steps.release.outputs.tag_name }}
sha: ${{ steps.release.outputs.sha }}
steps:
- uses: actions/checkout@v4
with:
ref: ${{ needs.prepare.outputs.release_sha }}
- name: Verify the approved version and commit
id: version
env:
APPROVED_SHA: ${{ needs.prepare.outputs.release_sha }}
RELEASE_PR: ${{ needs.prepare.outputs.release_pr }}
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
VERSION=$(python3 scripts/release/release.py check --sha "$APPROVED_SHA")
echo "version=$VERSION" >> "$GITHUB_OUTPUT"
gh pr list --repo "$GITHUB_REPOSITORY" --base main --state merged \
--label 'autorelease: pending' --limit 2 --json number,mergeCommit > "$RUNNER_TEMP/pending.json"
python3 - <<'PY'
import json, os
from pathlib import Path
pending = json.loads((Path(os.environ["RUNNER_TEMP"]) / "pending.json").read_text())
expected = [{"number": int(os.environ["RELEASE_PR"]), "mergeCommit": {"oid": os.environ["APPROVED_SHA"]}}]
if pending != expected:
raise SystemExit("Pending release changed while tests were running; rerun verification")
PY
- name: Create the tag and draft release after tests pass
id: release
uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
with:
config-file: .github/release-please-config.json
manifest-file: .github/release-please-manifest.json
target-branch: main
skip-github-pull-request: true
- name: Confirm Release Please tagged the verified commit
env:
APPROVED_SHA: ${{ needs.prepare.outputs.release_sha }}
CREATED_SHA: ${{ steps.release.outputs.sha }}
CREATED_TAG: ${{ steps.release.outputs.tag_name }}
CREATED: ${{ steps.release.outputs.release_created }}
VERSION: ${{ steps.version.outputs.version }}
run: |
test "$CREATED" = true
test "$CREATED_SHA" = "$APPROVED_SHA"
test "$CREATED_TAG" = "v$VERSION"
package:
needs: tag
uses: ./.github/workflows/release.yaml
permissions:
contents: write
with:
tag: ${{ needs.tag.outputs.tag }}
sha: ${{ needs.tag.outputs.sha }}
+74 -15
View File
@@ -1,30 +1,77 @@
name: Release
name: Build Release Draft
on:
push:
tags:
- "v*"
workflow_call:
inputs:
tag:
type: string
required: true
sha:
description: Commit already verified before tagging
type: string
required: true
workflow_dispatch:
inputs:
tag:
description: Existing draft tag to rebuild (e.g. v0.24.0)
required: true
type: string
concurrency:
group: release-draft-${{ inputs.tag }}
cancel-in-progress: false
permissions:
contents: write
jobs:
resolve:
runs-on: ubuntu-latest
outputs:
sha: ${{ steps.resolve.outputs.sha }}
steps:
- uses: actions/checkout@v4
with:
ref: refs/tags/${{ inputs.tag }}
fetch-depth: 0
- name: Verify the tag, version and approved commit
id: resolve
env:
TAG: ${{ inputs.tag }}
APPROVED_SHA: ${{ inputs.sha }}
run: |
CURRENT_SHA=$(git rev-parse HEAD)
python3 scripts/release/release.py check --tag "$TAG" --sha "${APPROVED_SHA:-$CURRENT_SHA}"
echo "sha=$CURRENT_SHA" >> "$GITHUB_OUTPUT"
test:
needs: resolve
if: github.event_name == 'workflow_dispatch' && inputs.sha == ''
uses: ./.github/workflows/test.yaml
with:
ref: ${{ needs.resolve.outputs.sha }}
release:
needs: test
needs: [resolve, test]
if: always() && needs.resolve.result == 'success' && (needs.test.result == 'success' || needs.test.result == 'skipped')
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
ref: ${{ needs.resolve.outputs.sha }}
fetch-depth: 0
- name: Require an unpublished draft
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TAG: ${{ inputs.tag }}
run: test "$(gh release view "$TAG" --json isDraft --jq .isDraft)" = true
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version: "1.23"
go-version-file: go.mod
- name: Set up pnpm
uses: pnpm/action-setup@v4
@@ -41,24 +88,36 @@ jobs:
- name: Build UI assets
run: cd ui && pnpm install --frozen-lockfile && pnpm run build
- name: Create UI dist archive
run: tar czf skillshare-ui-dist.tar.gz -C ui/dist .
- name: Create UI archive and reviewed release notes
env:
TAG: ${{ inputs.tag }}
run: |
tar czf skillshare-ui-dist.tar.gz -C ui/dist .
python3 scripts/release/release.py notes --tag "$TAG" > "$RUNNER_TEMP/release-notes.md"
- name: Run GoReleaser
- name: Build and upload draft assets
uses: goreleaser/goreleaser-action@v6
with:
version: latest
args: release --clean --skip=validate
version: v2.18.2
args: release --clean --release-notes=${{ runner.temp }}/release-notes.md
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
HOMEBREW_TAP_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
- name: Verify and upload the Homebrew formula and complete checksums
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TAG: ${{ inputs.tag }}
run: |
python3 scripts/release/release.py prepare-assets --assets dist
python3 scripts/release/release.py verify-assets --tag "$TAG" --assets dist
gh release upload "$TAG" dist/skillshare.rb dist/checksums.txt --clobber
- name: Add contributors to release notes
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TAG: ${{ inputs.tag }}
run: |
TAG="${GITHUB_REF#refs/tags/}"
PREV_TAG=$(git tag --sort=-v:refname | grep -v "^${TAG}$" | head -1)
PREV_TAG=$(git describe --tags --abbrev=0 "${TAG}^" 2>/dev/null || true)
if [ -z "$PREV_TAG" ]; then
echo "No previous tag found, skipping contributors"
+27 -5
View File
@@ -17,6 +17,11 @@ on:
- cron: "0 3 * * *"
workflow_dispatch:
workflow_call:
inputs:
ref:
description: Exact commit to verify for a release
type: string
default: ""
jobs:
unit-test:
@@ -24,6 +29,8 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@v4
with:
ref: ${{ inputs.ref || github.sha }}
- name: Check AI context routes
run: python3 scripts/ai-context.py check
@@ -31,13 +38,18 @@ jobs:
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version: "1.23"
go-version-file: go.mod
- name: Build
run: make build
- name: Formatting, lint and release metadata tests
run: |
make fmt-check lint
python3 -B -m unittest discover -s scripts/release -p '*_test.py'
- name: Unit Tests
run: go test -v -race ./internal/...
run: go test -v -race ./cmd/skillshare/... ./internal/...
integration-test:
runs-on: ${{ matrix.os }}
@@ -47,11 +59,13 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@v4
with:
ref: ${{ inputs.ref || github.sha }}
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version: "1.23"
go-version-file: go.mod
- name: Build Binary
run: make build
@@ -66,6 +80,8 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@v4
with:
ref: ${{ inputs.ref || github.sha }}
- name: Docker Sandbox Tests (Offline)
run: ./scripts/test_docker.sh
@@ -76,6 +92,8 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@v4
with:
ref: ${{ inputs.ref || github.sha }}
- name: Docker Sandbox Tests (Online)
run: ./scripts/test_docker_online.sh
@@ -85,11 +103,13 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@v4
with:
ref: ${{ inputs.ref || github.sha }}
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version: "1.23"
go-version-file: go.mod
- name: Red Team Test
run: make test-redteam
@@ -100,11 +120,13 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@v4
with:
ref: ${{ inputs.ref || github.sha }}
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version: "1.23"
go-version-file: go.mod
- name: Red Team Signal (Code Mutation)
run: make test-redteam-signal
+7 -4
View File
@@ -22,11 +22,11 @@ builds:
- -s -w -X main.version={{.Version}}
archives:
- format: tar.gz
- formats: [tar.gz]
name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
format_overrides:
- goos: windows
format: zip
formats: [zip]
checksum:
name_template: "checksums.txt"
@@ -42,14 +42,17 @@ changelog:
- "^ci:"
release:
draft: true
use_existing_draft: true
replace_existing_artifacts: true
extra_files:
- glob: skillshare-ui-dist.tar.gz
brews:
- repository:
- skip_upload: true
repository:
owner: runkids
name: homebrew-tap
token: "{{ .Env.HOMEBREW_TAP_TOKEN }}"
directory: Formula
homepage: https://github.com/runkids/skillshare
description: Share skills across AI CLI tools
@@ -8,16 +8,16 @@ description: >-
"what changed since last release", this is the skill to use. Do NOT manually
edit CHANGELOG.md without this skill — it ensures proper formatting,
user-perspective writing, and website changelog sync. For full release
workflows (tests, changelog, release notes, version bump, announcements),
workflows (Release PR review, tests, draft assets, publication, announcements),
use /release instead.
argument-hint: "[tag-version]"
metadata:
targets: [claude, universal]
---
Generate a CHANGELOG.md entry for a release. $ARGUMENTS specifies the tag version (e.g., `v0.16.0`) or omit to auto-detect via `git describe --tags --abbrev=0`.
Review or generate a user-facing changelog entry. Prefer the open Release Please PR and its manifest version for an upcoming release. For historical work, $ARGUMENTS specifies the requested tag or commit range.
**Scope**: This skill updates `CHANGELOG.md` and syncs the website changelog (`website/src/pages/changelog.md`). It does NOT generate RELEASE_NOTES, update version numbers, or handle the full release workflow — use `/release` for that.
**Scope**: This skill updates `CHANGELOG.md` and syncs the website changelog (`website/src/pages/changelog.md`). It does NOT generate RELEASE_NOTES, choose a new version, or handle the full release workflow — use `/release` for that.
Before acting, run `python3 scripts/ai-context.py release`. That topic is the source of truth for authorization, changelog content and synchronization rules; this skill retains the entry-generation workflow.
@@ -25,21 +25,18 @@ Before acting, run `python3 scripts/ai-context.py release`. That topic is the so
### Step 1: Determine Version Range
```bash
# Auto-detect latest tag
LATEST_TAG=$(git describe --tags --abbrev=0)
# Find previous tag
PREV_TAG=$(git describe --tags --abbrev=0 "${LATEST_TAG}^")
For an upcoming release, work on the Release PR branch and read `.github/release-please-manifest.json`. Verify the latest published tag and use its range to the Release PR head. Keep the proposed version; this skill does not authorize a version change. Tags may exist for unpublished drafts, so do not assume the highest local tag is the latest published release.
echo "Generating changelog: $PREV_TAG → $LATEST_TAG"
```
For historical work, use the user-requested tags or range.
### Step 2: Collect Commits
```bash
git log "${PREV_TAG}..${LATEST_TAG}" --oneline --no-merges
git log <previous-published-tag>..<release-pr-head-or-requested-tag> --oneline --no-merges
```
Review the generated Release Please entry before writing. Preserve useful manual examples and migration notes. Do not add a second entry for the same version.
### Step 3: Categorize Changes
Group commits by conventional commit type:
@@ -48,11 +45,11 @@ Group commits by conventional commit type:
|--------|----------|
| `feat` | New Features |
| `fix` | Bug Fixes |
| `refactor` | Refactoring |
| `docs` | Documentation |
| `perf` | Performance |
| `test` | Tests |
| `chore` | Maintenance |
| breaking change | Breaking Changes and migration notes |
| `revert` | Reverts, when user-visible |
Exclude test-only, CI-only, pure refactoring, documentation-only and internal maintenance entries from published notes.
### Step 4: Read Existing Entries for Style Reference
@@ -83,7 +80,7 @@ Write from the **user's perspective**. Only include changes users will notice or
### Step 6: Update CHANGELOG.md
Read existing `CHANGELOG.md` and insert new entry at the top, after the header. Match the style of the most recent entries exactly.
Edit the existing generated entry on the Release PR branch. If the requested historical entry does not exist, insert it at the appropriate position. Match the style of the most recent entries.
Structural conventions (based on actual entries):
```markdown
@@ -133,7 +130,16 @@ The website has its own changelog page at `website/src/pages/changelog.md`. Afte
- Website file has a `---` separator after the intro, before the first version entry
- The release entries themselves are identical in content
**How to sync**: Read the website changelog, then insert the same new entry after the `---` separator (line after intro paragraph), before the first existing version entry. Do NOT replace the entire file — only insert the new entry block.
For an upcoming Release PR, run inside the devcontainer:
```bash
python3 scripts/release/release.py sync
python3 scripts/release/release.py check
```
The helper normalizes the generated version heading, replaces or prepends only the newest website entry, and synchronizes the built-in skill metadata to the already proposed manifest version. It preserves website frontmatter, intro and historical entries. It does not choose or bump a version.
For historical corrections, edit the matching entry in both files directly; the helper handles only the current manifest release. Review the diff and run `python3 scripts/ai-context.py check`.
## Rules
+49 -99
View File
@@ -1,127 +1,77 @@
---
name: skillshare-release
description: >-
End-to-end release workflow for skillshare. Runs tests, generates changelog
(via /changelog), optionally writes local RELEASE_NOTES, updates version
numbers, commits, and drafts announcements. Use when the user says "release",
"prepare release", "cut a release", "release v0.19", or any request to
publish a new version. For changelog-only tasks, use /changelog instead.
argument-hint: "<version>"
Prepare and review skillshare releases using the Release Please PR, verify the
proposed version and changelog, inspect draft assets, and publish through the
manual Publish Release workflow when explicitly authorized. Use when the user
says "release", "prepare release", "cut a release", or asks to publish a new
version. For changelog-only tasks, use /changelog instead.
argument-hint: "[version]"
metadata:
targets: [claude, universal]
---
End-to-end release workflow for skillshare. $ARGUMENTS specifies the version (e.g., `v0.19.0`).
Prepare or review a skillshare release. An optional version argument is an explicit requested version, not permission to commit, merge, tag, push, or publish.
Before acting, run `python3 scripts/ai-context.py release testing`. Those topics are the source of truth for authorization, release artifacts and verification; this skill retains the release orchestration and draft formats.
## Prerequisites
- All feature work merged to current branch
- Working directory clean (`git status` shows no uncommitted changes)
Before acting, run `python3 scripts/ai-context.py release testing`. These topics are the source of truth for authorization, version policy, automation and verification.
## Workflow
### Phase 1: Validate
### 1. Identify the release
Run full test suite and code quality checks. Fix any failures before proceeding.
Inspect Git status, the latest published release and the open Release PR. Preserve unrelated work. The manifest at `.github/release-please-manifest.json` is the release version source; the development CLI still defaults to `dev`.
Pushes to `main` create or update a Release PR. If one is missing, report the workflow state and required repository permissions. Dispatch the Release Please workflow only when the user authorizes that external action.
For `0.x`, `fix` and `perf` increment patch; `feat` and breaking changes increment minor. A breaking change needs migration notes. Moving to `1.0.0` requires an explicit version decision. For an override, use a `Release-As: X.Y.Z` commit footer or a reviewed `release-as` configuration value; remove a configuration override after it has been consumed. Do not edit the tracking manifest by itself to request a release.
#### Explicit version requests
When the user requests a version such as `0.23.3`, prepare a `Release-As: 0.23.3` footer on a normal development commit that will reach `main` before the Release PR is merged. For a batch with multiple commits, adding it once to the final commit is sufficient; the override chooses the version for the entire pending release, including the earlier changes. Intermediate versions do not need to be published.
```text
fix: correct sync behavior
Release-As: 0.23.3
```
With merge or rebase-merge, preserve the footer in the development commit. With squash-merge, copy it into the final squash commit message on GitHub; do not assume the individual commit messages will be preserved. Keep the Conventional Commit subject and a blank line before the footer. If multiple pending commits request different versions, the newest override wins; inspect the pending range for conflicting requests before proceeding.
After the commit reaches `main`, verify that Release Please creates or updates the Release PR to the requested version. Review its manifest and synchronized metadata before merging. Adding a footer alone does not create the release tag or publish anything. Follow the existing authorization boundary when committing, pushing or merging.
### 2. Review the Release PR
Use `/changelog` to turn generated notes into user-facing prose and examples. Work on the Release PR branch, then synchronize and check its files inside the devcontainer:
```bash
make check # fmt-check + lint + test (builds binary first)
python3 scripts/release/release.py sync
python3 scripts/release/release.py check --tag vX.Y.Z
make check
python3 -m unittest discover -s scripts/release -p '*_test.py'
```
If tests fail: fix them, don't skip. Do not ask the user — fix and re-run.
Check the manifest, built-in skill metadata and both changelog copies. Bot-created or bot-updated PRs may require the maintainer to approve GitHub's native workflow prompt before CI runs. Never bypass that prompt.
### Phase 2: Changelog
Commit and push review edits, or merge the PR, only when explicitly authorized. Do not create a release tag locally: the automation tests the exact merged commit before creating the tag and draft.
Invoke `/changelog $VERSION` to generate the changelog entry.
### 3. Inspect the draft
This handles:
- Collecting commits since last tag
- Categorizing by conventional commit type
- Writing user-facing CHANGELOG.md entry
- Syncing website changelog (`website/src/pages/changelog.md`)
After the Release PR merges, the Release Please workflow tests its merge SHA, creates a draft and tag, and explicitly calls Build Release Draft. The workflow builds all six CLI archives and the UI archive, generates the Homebrew formula, verifies checksums and checks the packaged CLI version.
Review the output before proceeding.
Review the draft notes, migration guidance, tag and artifacts. A failed packaging job leaves an unpublished draft. Rerun the failed packaging job or, with authorization, dispatch Build Release Draft for that existing tag; do not create a second tag or change the version to hide a build failure.
### Phase 3: Release Notes Draft (Maintainer Only, Local by Default)
### 4. Optional local notes and announcements
Check if running as maintainer:
```bash
git config user.name # Should match "Willie" or maintainer identity
```
If the maintainer requests detailed local notes, follow the most recent `specs/RELEASE_NOTES_*.md` and write `specs/RELEASE_NOTES_<version>.md`. The ignored `specs/` files stay local unless the user explicitly asks to commit them. Do not force-add them by default.
**If maintainer**:
Draft announcements only when requested. Describe user-visible behavior, add examples and migration guidance, and avoid internal implementation details.
Read the most recent `specs/RELEASE_NOTES_*.md` as a style reference, then generate `specs/RELEASE_NOTES_<version>.md` (no `v` prefix, e.g., `RELEASE_NOTES_0.19.0.md`).
### 5. Publish only when authorized
Release notes are a local maintainer artifact by default. The `specs/` directory is gitignored; do **not** force-add or commit `specs/RELEASE_NOTES_<version>.md` unless the user explicitly asks for release notes to be committed.
Present the concrete draft and verification results. If publication is explicitly authorized, dispatch **Publish Release** with the exact `vX.Y.Z` tag. It verifies downloaded assets and the packaged CLI before publishing, then updates Homebrew and explicitly runs Docker Publish for the pinned tag commit.
Structure:
- Title: `# skillshare vX.Y.Z Release Notes`
- TL;DR section with numbered highlights
- One `##` section per feature/fix — describe **what changed** in plain language, with a CLI example or code block if relevant
- Include migration guide if breaking changes exist
Use this workflow rather than publishing directly from the GitHub draft page, so the complete distribution path runs. For a partial distribution failure, rerun the failed job with the same tag; never retag or publish an older version over the current one.
**Wording rules** (same user-facing standard as CHANGELOG):
- Describe **what changed** from the user's perspective, not how the code changed
- **Never mention**: function names, variable names, struct fields, file paths, Go syntax, internal APIs
- ✅ Good: "Sync now auto-creates missing target directories and shows what it did"
- ❌ Bad: "upgraded `Server.mu` from `sync.Mutex` to `sync.RWMutex` and applied a snapshot pattern across 30 handlers"
- Keep it concise — a short paragraph per feature is enough
## Report
**If not maintainer**: Skip this phase.
### Phase 4: Version Bump
Update the version in `skills/skillshare/SKILL.md` frontmatter:
```yaml
metadata:
version: vX.Y.Z
```
This ensures `skillshare upgrade --skill` detects the new version correctly.
### Phase 5: Commit & Tag
Commit and tag only when the release request includes it or the user confirms; the tag is what publishes.
```bash
git add CHANGELOG.md website/src/pages/changelog.md skills/skillshare/SKILL.md
# Only if the user explicitly asked to commit release notes:
# git add -f specs/RELEASE_NOTES_<version>.md
git commit -m "chore: release vX.Y.Z"
git tag vX.Y.Z
```
Do NOT push yet — wait for user confirmation.
### Phase 6: Draft Announcements
Prepare two drafts for user review:
1. **GitHub Release Notes** — concise, user-facing summary suitable for the GitHub release page. Shorter than RELEASE_NOTES, highlight top 3-5 changes with one-liners.
2. **Social media post** — 2-3 sentences max, casual tone, mention the version and 1-2 headline features. No hashtag spam.
**Tone**: short, direct. Don't oversell. The user will edit before posting.
### Phase 7: Present & Confirm
Show the user:
- [ ] Test results (pass/fail)
- [ ] CHANGELOG.md diff
- [ ] RELEASE_NOTES file (if generated, and whether it was left local or committed)
- [ ] Version bump diff
- [ ] GitHub release draft
- [ ] Social media draft
Wait for user approval before pushing:
```bash
git push origin HEAD --tags
```
## Rules
Apply `release` and `testing`. Never infer permission to push or publish from preparation work.
State the reviewed version, Release PR and draft, test results, artifact checks, and which external actions were actually performed. Distinguish local preparation, an unpublished draft, a published release and completed distribution.
+2 -1
View File
@@ -10,8 +10,9 @@ COPY go.mod go.sum ./
RUN go mod download
COPY . .
ARG TARGETARCH=amd64
ARG VERSION=dev
RUN CGO_ENABLED=0 GOOS=linux GOARCH=${TARGETARCH} \
go build -trimpath -ldflags="-s -w" -o /skillshare ./cmd/skillshare
go build -trimpath -ldflags="-s -w -X main.version=${VERSION}" -o /skillshare ./cmd/skillshare
# Stage 2: Minimal CI runtime
FROM debian:bookworm-slim
+2 -1
View File
@@ -9,8 +9,9 @@ COPY go.mod go.sum ./
RUN go mod download
COPY . .
ARG TARGETARCH=amd64
ARG VERSION=dev
RUN CGO_ENABLED=0 GOOS=linux GOARCH=${TARGETARCH} \
go build -trimpath -ldflags="-s -w" -o /skillshare ./cmd/skillshare
go build -trimpath -ldflags="-s -w -X main.version=${VERSION}" -o /skillshare ./cmd/skillshare
# Stage 2: Minimal runtime
FROM debian:bookworm-slim
+32 -240
View File
@@ -12,260 +12,52 @@ skillshare ships at high velocity — `v0.20.5` through `v0.20.9` landed in thre
The existing `release.yaml` / GoReleaser setup is solid — the only friction is the manual steps that precede it.
## Proposed Solution
## Implemented design
Adopt [release-please](https://github.com/googleapis/release-please) to automate the three manual steps above, leaving `release.yaml` and GoReleaser completely unchanged.
The configuration and workflows implement a version-first, draft-first release process. This supersedes the original proposal's assumption that a `GITHUB_TOKEN` tag push would start the existing workflows unchanged. See [the release runbook](../wiki/release.md) for operating instructions.
### How it works
### Version policy
1. Commits land on `main` using Conventional Commit messages (`feat:`, `fix:`, `perf:`, etc.).
2. release-please opens (or keeps updated) a **Release PR** — e.g. `chore(main): release v0.20.10` — containing the bumped version and generated `CHANGELOG.md` diff.
3. When ready to ship, **merge the PR**. release-please creates the `v*` tag.
4. The existing `release.yaml` fires on the tag — GoReleaser, Homebrew tap update, and contributor credits all run exactly as they do today.
The tracking manifest starts at the published `0.23.1`, with its exact commit as the bootstrap boundary. Existing changelog history is retained.
Step 4 requires zero changes to `.goreleaser.yaml` or `release.yaml`.
- `fix` and `perf`: patch increment.
- `feat`: minor increment, including before 1.0.
- Breaking change: minor increment before 1.0, with migration notes; major increment after 1.0.
- `1.0.0` or another explicitly chosen version: a `Release-As: X.Y.Z` commit footer or a reviewed `release-as` configuration override, removed after use.
- Documentation, tests and internal maintenance do not create ordinary release entries by themselves.
---
The manifest, built-in skill and both changelog copies must agree. Tag, binary version, archive names, Homebrew formula and Docker images use that same approved version.
### New files
### Workflow
#### `.github/workflows/pr-check.yml`
1. **Release Please** runs on pushes to `main`, creating or updating a Release PR without tagging or publication. A post-processing helper normalizes the generated heading, updates the built-in skill metadata, and synchronizes only the newest website changelog entry while preserving frontmatter and history.
2. The maintainer reviews the version, notes, examples and migration instructions before merging. Both ordinary merge and squash-merge are supported. Conventional Commit messages are required for meaningful version calculation, but this change does not modify merge permissions or branch protection.
3. For a merged pending Release PR, the existing Test workflow checks its exact merge SHA. The pipeline checks that this is still the only pending candidate before proceeding.
4. Release Please creates the `vX.Y.Z` tag and a GitHub draft (`draft` and `force-tag-creation` enabled). Packaging is an explicit reusable-workflow call because `GITHUB_TOKEN` tag pushes do not trigger other workflows.
5. **Build Release Draft** uses GoReleaser to build all CLI platforms and UI assets. Homebrew upload is disabled during draft construction. Its generated formula is attached to the draft and included in checksums. Checksums, formula identity and the actual Linux CLI version are verified.
6. The maintainer runs **Publish Release** with the reviewed tag. The workflow downloads and verifies assets before publishing, updates the Homebrew tap, and explicitly runs Docker Publish for the same tag commit. A tag alone does not distribute a draft.
Enforces Conventional Commit format on every PR title so release-please has well-formed input. Without consistent commit messages the generated changelog is noisy.
### Configuration and code
```yaml
name: PR Title Check
- `.github/release-please-config.json` and `.github/release-please-manifest.json`
- `.github/workflows/release-please.yml`, `release.yaml`, `publish-release.yml`, `docker-publish.yml`, and `test.yaml`
- `.goreleaser.yaml`: draft builds, existing-draft reuse, unpublished Homebrew formula
- `scripts/release/release.py` and its regression tests
- Release Dockerfiles: inject the approved binary version
- Release/changelog skill adapters and the release runbook
on:
pull_request:
types: [opened, edited, synchronize, reopened]
### Repository setup
jobs:
check-title:
name: Validate PR title
runs-on: ubuntu-latest
steps:
- name: Check Conventional Commit format
env:
PR_TITLE: ${{ github.event.pull_request.title }}
run: |
# Accepts: type(scope): description
# type: description
# where type is one of the conventional-commit vocabulary
PATTERN='^(feat|fix|chore|docs|test|ci|perf|revert|build|style|refactor)(\([^)]+\))?!?: .+'
if echo "$PR_TITLE" | grep -Eq "$PATTERN"; then
echo "OK: $PR_TITLE"
else
echo "FAIL: PR title does not follow Conventional Commits."
echo ""
echo "Required format:"
echo " type(scope): short description"
echo " type: short description"
echo ""
echo "Examples:"
echo " feat(cli): add zed target"
echo " fix: respect .skillignore in audit"
echo " chore(deps): bump golang.org/x/sys to v0.22"
echo " perf: cache skill index on first load"
exit 1
fi
```
The maintainer must enable **Allow GitHub Actions to create and approve pull requests** in the repository's Actions settings. The workflows declare their own write permissions. PR checks created or updated with `GITHUB_TOKEN` may require the native **Approve workflows to run** action; do not bypass it.
#### `.github/workflows/release-please.yml`
This implementation does not change repository permissions, merge rules, tag protections, secrets, or external publication state.
Runs release-please on every push to `main`. Also exposes a manual escape hatch (`workflow_dispatch`) that pushes a tag directly — use this if release-please is broken or a hotfix needs to ship immediately without waiting for a Release PR merge.
### Recovery
```yaml
name: Release Please
For a failed draft build, rerun the failed job or dispatch Build Release Draft with the existing draft tag. A manual rebuild verifies and tests the pinned tag commit. For distribution failures, rerun Publish Release with the same tag, or Docker Publish for an already published tag. Never retag or redistribute an older version over the current published version.
on:
push:
branches: [main]
workflow_dispatch:
inputs:
tag_name:
description: 'Tag to push directly (e.g. v0.20.10). Bypasses Release PR — use only as a last resort.'
required: true
### Validation
permissions:
contents: write
pull-requests: write
Run the release helper regression tests, metadata checks, actionlint and the pinned GoReleaser configuration check inside the devcontainer, followed by the repository's required `make check`. Verify Release Please version behavior using the same library version bundled with the pinned action. Local validation does not establish live GitHub permissions or publication behavior.
jobs:
release-please:
name: Release Please
runs-on: ubuntu-latest
if: github.event_name == 'push'
steps:
- uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v4.4.0
with:
token: ${{ secrets.GITHUB_TOKEN }}
config-file: .github/release-please-config.json
manifest-file: .github/release-please-manifest.json
manual-tag:
name: Push Manual Release Tag
runs-on: ubuntu-latest
if: github.event_name == 'workflow_dispatch'
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Validate tag format
run: |
TAG="${{ github.event.inputs.tag_name }}"
if ! echo "$TAG" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
echo "Invalid tag format: $TAG — must match vMAJOR.MINOR.PATCH"
exit 1
fi
- name: Push tag
run: |
TAG="${{ github.event.inputs.tag_name }}"
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git tag "$TAG"
git push origin "$TAG"
```
When a tag is pushed by either path, `release.yaml` fires as it always has.
#### `.github/release-please-config.json`
```json
{
"$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
"release-type": "go",
"bump-minor-pre-major": true,
"bump-patch-for-minor-pre-major": true,
"changelog-sections": [
{ "type": "feat", "section": "### New Features" },
{ "type": "fix", "section": "### Bug Fixes" },
{ "type": "perf", "section": "### Performance" },
{ "type": "revert", "hidden": true},
{ "type": "docs", "hidden": true },
{ "type": "chore", "hidden": true },
{ "type": "test", "hidden": true },
{ "type": "ci", "hidden": true },
{ "type": "build", "hidden": true },
{ "type": "style", "hidden": true },
{ "type": "refactor","hidden": true }
],
"packages": {
".": {}
}
}
```
The section names map directly to the existing `CHANGELOG.md` headings (`### New Features`, `### Bug Fixes`, `### Performance`), so the generated output matches the current style without post-processing.
#### `.github/release-please-manifest.json`
Bootstrapped to the current release. release-please updates this automatically on each release.
```json
{
".": "0.20.9"
}
```
---
### Repository settings that must accompany this change
These are not automated by this proposal but are required for the workflow to function correctly.
#### Squash merges only
release-please reads the **merge commit message** to decide what version bump the Release PR itself represents. If regular merge commits or rebase-and-merge are allowed, the commit that release-please uses to detect its own PR may be malformed and it will open a duplicate Release PR or loop.
In **Settings → General → Pull Requests**:
- [x] Allow squash merging — set default message to "Pull request title and description"
- [ ] Allow merge commits — **disable**
- [ ] Allow rebase merging — **disable**
#### Branch protection on `main`
In **Settings → Branches → main**:
- [x] Require a pull request before merging
- [x] Require status checks to pass — add `check-title` (from `pr-check.yml`) and the existing `unit-test` job
- [x] Require branches to be up to date before merging
- [x] Do not allow bypassing the above settings (maintainer should merge the Release PR like any other PR)
#### Tag protection on `v*`
In **Settings → Tags → Protected tags**, add the pattern `v*`. This prevents a mistyped local `git push --tags` from publishing a broken release and ensures that all `v*` tags originate from CI (either the release-please job or the `manual-tag` fallback).
Exception: the `GITHUB_TOKEN` used by CI is exempt from tag protection rules by default, so `release-please.yml` and `manual-tag` both continue to work without additional configuration.
---
### Manual fallback / escape hatch
If release-please is broken, a PR is stuck, or a hotfix needs to ship immediately:
1. Go to **Actions → Release Please → Run workflow**.
2. Enter the tag to publish (e.g. `v0.20.10`).
3. The `manual-tag` job pushes the tag; `release.yaml` fires and GoReleaser runs as normal.
This means the existing fully-manual flow (local `git tag && git push --tags`) still works for the maintainer if needed — the tag protection only blocks non-CI pushes for non-maintainers.
---
### Migration path
1. Add `release-please-config.json` and seed `release-please-manifest.json` with `"0.20.9"` (the current latest).
2. Add `pr-check.yml` and `release-please.yml`.
3. Update branch protection and squash-merge settings.
4. Enable tag protection on `v*`.
5. From this point forward, use Conventional Commit PR titles. The first merge will open a Release PR.
No changes to `.goreleaser.yaml`, `release.yaml`, `docker-publish.yml`, or `test.yaml`.
---
### Conventional Commit vocabulary quick reference
| Prefix | Semver effect | Appears in changelog |
|---|---|---|
| `feat:` / `feat(scope):` | minor bump | Yes — New Features |
| `fix:` / `fix(scope):` | patch bump | Yes — Bug Fixes |
| `perf:` / `perf(scope):` | patch bump | Yes — Performance |
| `feat!:` or `BREAKING CHANGE:` footer | major bump | Yes — Breaking Changes |
| `revert:` | patch bump | Yes — Reverts |
| `docs:` `chore:` `test:` `ci:` `build:` `style:` `refactor:` | patch bump | Hidden |
The `.goreleaser.yaml` `changelog.filters.exclude` list already excludes `^docs:`, `^test:`, and `^ci:` — consistent with the hidden sections above, so GoReleaser-generated release notes and the release-please `CHANGELOG.md` will agree.
## Alternatives Considered
**Keep the manual flow.** Zero effort, but manual CHANGELOG entries and version decisions remain the highest-friction part of shipping at the current cadence.
**Use `semantic-release` instead.** More powerful but significantly more opinionated — it publishes on every push to `main` with no review gate. The release-please Release PR model gives a natural merge-when-ready gate that fits a single-maintainer project.
**Generate the changelog from GoReleaser only.** GoReleaser already generates release notes, but they live only in the GitHub release — not in `CHANGELOG.md`, and GoReleaser does not manage version bumps or tagging. release-please fills both gaps.
## Scope
- [ ] Small (1-3 files, < 200 lines)
- [x] Medium (3-10 files, 200-500 lines)
- [ ] Large (10+ files, 500+ lines)
New files: `.github/workflows/pr-check.yml`, `.github/workflows/release-please.yml`, `.github/release-please-config.json`, `.github/release-please-manifest.json` — all configuration, no Go source changes.
## Open Questions
- **CHANGELOG.md bootstrap.** The existing `CHANGELOG.md` is 2700+ lines of manually authored content. release-please will prepend generated entries above it. Should the file be kept as-is (clean separation), or should the old content be archived to a separate file on migration?
- **Release Gated:** Releases are fully gated, a release will not be published until the core maintainer merges the PR. Alternatively, if ever needed you have full control to create a release manually via the CI by supplying a tag i.e. `v0.22.0`
## Additional Comments
If you are interested to see this in a live project see the following projects that I have implemented this in:
1. [ssmctl](https://github.com/rhysmcneill/ssmctl/pull/108)
2. [skylos](https://github.com/duriantaco/skylos/pull/537)
3. [typo](https://github.com/yuluo-yx/typo/pull/170)
Furthermore, I have implemented this in many more personal, and professional repos (private, not public). This workflow will enhance your workflow, automate everything, you just need to push the button to release when you are happy - It will allow you to focus on things that matter - developing, and fixing bugs. :)
The existing `brews` generator is deprecated in GoReleaser v2.18.2: configuration checking reports status 2, while the complete isolated build succeeds with validation enabled. Preserve the current Homebrew formula interface; a cask migration is outside this change.
+165
View File
@@ -0,0 +1,165 @@
#!/usr/bin/env python3
"""Synchronize release metadata and verify the exact artifacts before publication."""
import argparse
import hashlib
import json
from pathlib import Path
import platform
import re
import shutil
import subprocess
import tarfile
import tempfile
VERSION = r"(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)"
HEADING = re.compile(
rf"^###? \[?v?({VERSION})\]?(?:\([^\n]*\))?"
r"(?: - (\d{4}-\d{2}-\d{2})| \((\d{4}-\d{2}-\d{2})\))[ \t]*$",
re.MULTILINE,
)
SKILL_VERSION = re.compile(rf"^( version: )v({VERSION})$", re.MULTILINE)
def manifest_version(root):
version = json.loads((root / ".github/release-please-manifest.json").read_text())["."]
if not re.fullmatch(VERSION, version):
raise ValueError("Only stable X.Y.Z release versions are supported")
return version
def first_entry(text):
headings = list(HEADING.finditer(text))
if not headings:
raise ValueError("No dated release heading found")
first = headings[0]
end = headings[1].start() if len(headings) > 1 else len(text)
return first, end, text[first.start():end].rstrip() + "\n\n"
def sync(root):
version = manifest_version(root)
changelog = root / "CHANGELOG.md"
text = changelog.read_text()
heading, end, entry = first_entry(text)
if heading[1] != version:
raise ValueError("Changelog version differs from the release manifest")
date = heading[2] or heading[3]
entry = f"## [{version}] - {date}" + entry[entry.index("\n"):]
website = root / "website/src/pages/changelog.md"
web_text = website.read_text()
web_heading, web_end, _ = first_entry(web_text)
if tuple(map(int, web_heading[1].split("."))) > tuple(map(int, version.split("."))):
raise ValueError("Refusing to replace a newer website release")
insertion_end = web_end if web_heading[1] == version else web_heading.start()
skill = root / "skills/skillshare/SKILL.md"
skill_text, count = SKILL_VERSION.subn(rf"\g<1>v{version}", skill.read_text())
if count != 1:
raise ValueError("Expected exactly one built-in skill metadata version")
changelog.write_text(text[:heading.start()] + entry + text[end:])
website.write_text(web_text[:web_heading.start()] + entry + web_text[insertion_end:])
skill.write_text(skill_text)
def check(root, tag=None, sha=None):
version = manifest_version(root)
if tag is not None and tag != f"v{version}":
raise ValueError("Tag differs from the release manifest")
if sha is not None:
actual = subprocess.check_output(["git", "rev-parse", "HEAD"], cwd=root, text=True).strip()
if not re.fullmatch(r"[0-9a-f]{40}", sha) or actual != sha:
raise ValueError("Checkout differs from the approved release commit")
_, _, entry = first_entry((root / "CHANGELOG.md").read_text())
heading, _, web_entry = first_entry((root / "website/src/pages/changelog.md").read_text())
if not entry.startswith(f"## [{version}] - ") or heading[1] != version or entry != web_entry:
raise ValueError("The manifest and both changelog entries must match")
matches = SKILL_VERSION.findall((root / "skills/skillshare/SKILL.md").read_text())
if len(matches) != 1 or matches[0][1] != version:
raise ValueError("Built-in skill version differs from the release manifest")
return version
def required_assets(version):
return {
f"skillshare_{version}_{os_name}_{arch}.{('zip' if os_name == 'windows' else 'tar.gz')}"
for os_name in ("darwin", "linux", "windows")
for arch in ("amd64", "arm64")
} | {"skillshare-ui-dist.tar.gz", "skillshare.rb"}
def prepare_assets(directory):
shutil.copyfile(directory.parent / "skillshare-ui-dist.tar.gz", directory / "skillshare-ui-dist.tar.gz")
formula = directory / "homebrew/Formula/skillshare.rb"
shutil.copyfile(formula, directory / "skillshare.rb")
checksum_file = directory / "checksums.txt"
lines = [line for line in checksum_file.read_text().splitlines() if not line.endswith(" skillshare.rb")]
digest = hashlib.sha256(formula.read_bytes()).hexdigest()
checksum_file.write_text("\n".join(lines) + f"\n{digest} skillshare.rb\n")
def verify_assets(root, directory, tag):
version = check(root, tag)
checksums = {}
for line in (directory / "checksums.txt").read_text().splitlines():
match = re.fullmatch(r"([0-9a-f]{64}) (.+)", line)
if not match or match[2] in checksums:
raise ValueError("Malformed or duplicate checksum entry")
checksums[match[2]] = match[1]
if set(checksums) != required_assets(version):
raise ValueError("Checksums must contain all six archives, UI assets and the Homebrew formula")
for name, digest in checksums.items():
if hashlib.sha256((directory / name).read_bytes()).hexdigest() != digest:
raise ValueError(f"Checksum mismatch: {name}")
formula = (directory / "skillshare.rb").read_text()
if f'version "{version}"' not in formula:
raise ValueError("Homebrew formula version differs from the release manifest")
urls = re.findall(r'url "(https://github.com/runkids/skillshare/releases/download/[^\"]+)"', formula)
prefix = f"https://github.com/runkids/skillshare/releases/download/{tag}/"
if not urls or any(not url.startswith(prefix) or url[len(prefix):] not in checksums for url in urls):
raise ValueError("Homebrew formula must download this release's verified archives")
# Read only the expected binary, never extract arbitrary archive paths.
arch = {"x86_64": "amd64", "aarch64": "arm64"}[platform.machine()]
with tarfile.open(directory / f"skillshare_{version}_linux_{arch}.tar.gz") as archive:
member = archive.getmember("skillshare")
if not member.isfile():
raise ValueError("Expected a regular skillshare binary in the Linux archive")
with tempfile.TemporaryDirectory(prefix="skillshare-release-binary-") as temp:
binary = Path(temp) / "skillshare"
binary.write_bytes(archive.extractfile(member).read())
binary.chmod(0o700)
output = subprocess.check_output([str(binary), "--version"], text=True).strip()
if output != f"skillshare v{version}":
raise ValueError("Packaged CLI version differs from the release manifest")
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("command", choices=("sync", "check", "notes", "prepare-assets", "verify-assets"))
parser.add_argument("--root", type=Path, default=Path.cwd())
parser.add_argument("--tag")
parser.add_argument("--sha")
parser.add_argument("--assets", type=Path)
args = parser.parse_args()
try:
if args.command == "sync":
sync(args.root)
check(args.root)
elif args.command == "check":
print(check(args.root, args.tag, args.sha))
elif args.command == "notes":
check(args.root, args.tag)
print(first_entry((args.root / "CHANGELOG.md").read_text())[2].split("\n", 1)[1].strip())
else:
if args.assets is None or (args.command == "verify-assets" and args.tag is None):
parser.error("--assets is required; verify-assets also requires --tag")
if args.command == "prepare-assets":
prepare_assets(args.assets)
else:
verify_assets(args.root, args.assets, args.tag)
except (ValueError, KeyError) as error:
parser.exit(1, f"Release verification failed: {error}\n")
if __name__ == "__main__":
main()
+145
View File
@@ -0,0 +1,145 @@
import hashlib
import io
import json
from pathlib import Path
import subprocess
import tarfile
import tempfile
import unittest
from release import check, first_entry, prepare_assets, required_assets, sync, verify_assets
class ReleaseTest(unittest.TestCase):
def setUp(self):
self.temp = tempfile.TemporaryDirectory(prefix="skillshare-release-test-")
self.addCleanup(self.temp.cleanup)
self.root = Path(self.temp.name)
self.write(".github/release-please-manifest.json", json.dumps({".": "0.24.0"}))
self.history = "## [0.23.1] - 2026-10-01\n\n- Previous release.\n"
self.entry = "## [0.24.0] - 2026-10-02\n\n### New Features\n\n- **Example** — `skillshare check`.\n\n"
self.prefix = "---\ntitle: Changelog\n---\n\n# Changelog\n\nKeep this intro.\n\n---\n\n"
self.write("CHANGELOG.md", "# Changelog\n\n" + self.entry + self.history)
self.write("website/src/pages/changelog.md", self.prefix + self.history)
self.write("skills/skillshare/SKILL.md", "---\nname: skillshare\nmetadata:\n version: v0.23.1\n---\n\nKeep this skill.\n")
def write(self, path, text):
target = self.root / path
target.parent.mkdir(parents=True, exist_ok=True)
target.write_text(text)
def test_sync_normalizes_release_please_heading_and_preserves_history(self):
generated = self.entry.replace("[0.24.0] - 2026-10-02", "[0.24.0](https://github.com/runkids/skillshare/compare/v0.23.1...v0.24.0) (2026-10-02)")
self.write("CHANGELOG.md", "# Changelog\n\n" + generated + self.history)
sync(self.root)
self.assertEqual(check(self.root, "v0.24.0"), "0.24.0")
self.assertEqual((self.root / "website/src/pages/changelog.md").read_text(), self.prefix + self.entry + self.history)
self.assertEqual((self.root / "CHANGELOG.md").read_text(), "# Changelog\n\n" + self.entry + self.history)
self.assertIn("Keep this skill.", (self.root / "skills/skillshare/SKILL.md").read_text())
def test_sync_replaces_existing_entry_and_is_idempotent(self):
sync(self.root)
self.write("CHANGELOG.md", "# Changelog\n\n" + self.entry.replace("Example", "Reviewed example") + self.history)
sync(self.root)
first = (self.root / "website/src/pages/changelog.md").read_text()
sync(self.root)
self.assertEqual(first, (self.root / "website/src/pages/changelog.md").read_text())
self.assertEqual(first.count("## [0.24.0]"), 1)
self.assertIn("Reviewed example", first)
def test_sync_normalizes_patch_release_heading(self):
self.write(".github/release-please-manifest.json", json.dumps({".": "0.23.2"}))
generated = self.entry.replace("## [0.24.0] - 2026-10-02", "### [0.23.2](https://example.test/compare) (2026-10-02)")
self.write("CHANGELOG.md", "# Changelog\n\n" + generated + self.history)
sync(self.root)
self.assertEqual(check(self.root, "v0.23.2"), "0.23.2")
def test_check_rejects_different_tag_skill_and_website(self):
sync(self.root)
with self.assertRaisesRegex(ValueError, "Tag differs"):
check(self.root, "v0.24.1")
self.write("skills/skillshare/SKILL.md", "metadata:\n version: v0.23.1\n")
with self.assertRaisesRegex(ValueError, "Built-in skill"):
check(self.root)
sync(self.root)
self.write("website/src/pages/changelog.md", self.prefix + self.entry.replace("Example", "Different") + self.history)
with self.assertRaisesRegex(ValueError, "changelog entries"):
check(self.root)
def test_sync_rejects_newer_website_without_writing_other_files(self):
self.write("website/src/pages/changelog.md", self.prefix + self.entry.replace("0.24.0", "0.25.0") + self.history)
before = (self.root / "skills/skillshare/SKILL.md").read_text()
with self.assertRaisesRegex(ValueError, "newer website"):
sync(self.root)
self.assertEqual(before, (self.root / "skills/skillshare/SKILL.md").read_text())
def test_check_rejects_a_different_release_commit(self):
sync(self.root)
subprocess.run(["git", "init", "-q"], cwd=self.root, check=True)
subprocess.run(["git", "add", "."], cwd=self.root, check=True)
subprocess.run(["git", "-c", "user.name=Release Test", "-c", "user.email=release@example.test", "commit", "-qm", "fixture"], cwd=self.root, check=True)
sha = subprocess.check_output(["git", "rev-parse", "HEAD"], cwd=self.root, text=True).strip()
self.assertEqual(check(self.root, sha=sha), "0.24.0")
with self.assertRaisesRegex(ValueError, "approved release commit"):
check(self.root, sha="0" * 40)
def test_notes_include_only_current_release(self):
_, _, entry = first_entry((self.root / "CHANGELOG.md").read_text())
self.assertIn("Example", entry)
self.assertNotIn("Previous release", entry)
def assets(self, binary_version="0.24.0"):
sync(self.root)
directory = self.root / "dist"
directory.mkdir()
for name in required_assets("0.24.0") - {"skillshare.rb", "skillshare-ui-dist.tar.gz"}:
(directory / name).write_bytes(b"release asset")
(self.root / "skillshare-ui-dist.tar.gz").write_bytes(b"release asset")
binary = f"#!/bin/sh\necho 'skillshare v{binary_version}'\n".encode()
for arch in ("amd64", "arm64"):
with tarfile.open(directory / f"skillshare_0.24.0_linux_{arch}.tar.gz", "w:gz") as archive:
member = tarfile.TarInfo("skillshare")
member.size = len(binary)
archive.addfile(member, io.BytesIO(binary))
self.write("dist/homebrew/Formula/skillshare.rb", 'class Skillshare < Formula\n version "0.24.0"\n url "https://github.com/runkids/skillshare/releases/download/v0.24.0/skillshare_0.24.0_darwin_arm64.tar.gz"\nend\n')
lines = [f"{hashlib.sha256(path.read_bytes()).hexdigest()} {path.name}" for path in directory.iterdir() if path.is_file()]
lines.append(f"{hashlib.sha256((self.root / 'skillshare-ui-dist.tar.gz').read_bytes()).hexdigest()} skillshare-ui-dist.tar.gz")
(directory / "checksums.txt").write_text("\n".join(lines) + "\n")
prepare_assets(directory)
return directory
def test_complete_assets_include_formula_and_match_binary_version(self):
directory = self.assets()
prepare_assets(directory)
verify_assets(self.root, directory, "v0.24.0")
self.assertEqual((directory / "checksums.txt").read_text().count(" skillshare.rb"), 1)
def test_assets_reject_changed_bytes(self):
directory = self.assets()
(directory / "skillshare-ui-dist.tar.gz").write_bytes(b"tampered")
with self.assertRaisesRegex(ValueError, "Checksum mismatch"):
verify_assets(self.root, directory, "v0.24.0")
def test_assets_reject_missing_platform_checksum(self):
directory = self.assets()
checksum_file = directory / "checksums.txt"
checksum_file.write_text("\n".join(line for line in checksum_file.read_text().splitlines() if "windows_arm64" not in line) + "\n")
with self.assertRaisesRegex(ValueError, "all six archives"):
verify_assets(self.root, directory, "v0.24.0")
def test_assets_reject_wrong_packaged_binary_version(self):
directory = self.assets(binary_version="dev")
with self.assertRaisesRegex(ValueError, "Packaged CLI version"):
verify_assets(self.root, directory, "v0.24.0")
def test_assets_reject_formula_pointing_at_another_release(self):
directory = self.assets()
formula = directory / "homebrew/Formula/skillshare.rb"
formula.write_text(formula.read_text().replace("download/v0.24.0/", "download/v0.23.1/"))
prepare_assets(directory)
with self.assertRaisesRegex(ValueError, "this release's verified archives"):
verify_assets(self.root, directory, "v0.24.0")
if __name__ == "__main__":
unittest.main()
+27 -2
View File
@@ -18,6 +18,27 @@ Version headings use `[X.Y.Z]` without a `v` prefix and include the date. Featur
## Full Release
### Release Please automation
The release version is recorded in `.github/release-please-manifest.json`. The initial baseline is the published `v0.23.1` commit, also pinned as `bootstrap-sha` in `.github/release-please-config.json`; do not bump it merely to install automation. The development CLI defaults to `dev`, while GoReleaser and release Docker builds inject the approved version.
For `0.x`, fixes and performance changes increment patch; new features and breaking changes increment minor. Breaking changes require migration notes. Moving to `1.0.0` is an explicit maintainer decision. Use a `Release-As: X.Y.Z` commit footer or a reviewed `release-as` configuration override for a specific version; remove a configuration override after that release. Do not edit the manifest alone to request a bump.
For an explicit version such as `0.23.3`, put `Release-As: 0.23.3` after a blank line in a normal development commit that will reach `main` before merging the Release PR. A single footer on the final commit of a batch is sufficient for the entire pending release; intermediate versions may be skipped. Preserve the footer when merging or rebasing. For squash-merge, copy it into the final squash commit message on GitHub. If pending commits contain conflicting version requests, the newest override wins. Verify the resulting Release PR's proposed version before merging; the footer itself neither tags nor publishes a release. See the [Release Please version override documentation](https://github.com/googleapis/release-please#how-do-i-change-the-version-number).
1. A push to `main` runs **Release Please**. With no merged release pending, it creates or updates a Release PR and synchronizes its manifest version, built-in skill version and newest changelog entry in both files.
2. Review the proposed version and user-facing notes on the Release PR branch. `python3 scripts/release/release.py sync` normalizes the heading and syncs the files; `check` verifies their agreement. Run these helpers inside the devcontainer. Bot PR creation and updates using `GITHUB_TOKEN` may leave PR CI awaiting the maintainer's native **Approve workflows to run** prompt.
3. Merging the Release PR selects its exact merge SHA for the reusable Test workflow. Formatting, lint, Go unit/integration tests, release helper tests, Docker sandbox tests and applicable red-team jobs must pass before tagging. If another merged pending release appears during testing, the tag job stops.
4. Release Please creates the stable tag and an unpublished draft with `force-tag-creation`. The workflow explicitly calls **Build Release Draft**; it does not depend on a `GITHUB_TOKEN` tag push triggering another workflow.
5. GoReleaser builds all six CLI archives, UI assets and an unpublished Homebrew formula. The draft remains unpublished. The helper verifies filenames, all checksums, formula version/URLs and the actual native Linux CLI version. Contributors are added to the reviewed changelog-based release notes.
6. After reviewing the draft, explicitly authorize **Publish Release** with the exact tag. It verifies the downloaded assets again before publication, then updates Homebrew and explicitly calls Docker Publish. Release Docker images use the same version and tag commit. Draft tags never publish Docker images or update the tap.
For automation setup, the repository must allow GitHub Actions to create pull requests under **Settings > Actions > General > Workflow permissions**. Workflow YAML grants scoped write permissions; it does not change repository settings or native approval rules. Keep Conventional Commit messages on `main`; ordinary merge and squash-merge of a Release PR are both supported.
For failed draft packaging, rerun the failed packaging job or dispatch **Build Release Draft** for its existing tag. Manual draft rebuilds test the tag commit again. For a publication/distribution failure, rerun **Publish Release** for the same tag; it tolerates an already published release and unchanged tap formula. Docker Publish also has a published-tag recovery input. Older versions cannot overwrite current distribution. Do not recreate a tag, force-push, or publish directly through the draft page as a substitute for the complete workflow.
### Local release preparation
Before starting:
- Confirm the requested version and branch.
@@ -28,8 +49,8 @@ Then:
1. Generate and review the changelog.
2. For maintainer-only release notes, follow the newest `specs/RELEASE_NOTES_*.md` and write user-facing prose to `specs/RELEASE_NOTES_<version>.md`.
3. Verify the current version location from source before bumping it; do not assume a fixed field still exists.
4. Commit or tag only when explicitly requested. Stage only task-owned files and follow recent repository release commits.
3. Review the manifest's proposed version and synchronize the Release PR files; do not perform a separate manual version bump.
4. Commit review edits or merge the Release PR only when explicitly requested. Stage only task-owned files. The automation owns release tagging after verification.
5. Draft concise GitHub release notes and a social announcement.
6. Present tests, diffs, local-only artifacts, and commit/tag state; obtain confirmation before pushing or publishing.
@@ -38,3 +59,7 @@ Release notes are local maintainer artifacts by default. Never force-add an igno
## Verification and Report
Report actual test results, whether both changelog copies match, the verified version location, commit/tag state, and external actions not performed. If the working tree is dirty, list the unrelated changes that were preserved.
Release automation checks: run `python3 -m unittest discover -s scripts/release -p '*_test.py'` and `python3 scripts/release/release.py check` inside the devcontainer. Validate changed workflows with actionlint and validate `.goreleaser.yaml` with the pinned GoReleaser version. A local check cannot prove GitHub permissions, native CI approvals or external publication; report those separately.
GoReleaser v2.18.2 reports the existing `brews` generator as deprecated, so `goreleaser check` exits with status 2 despite a valid configuration. A full isolated `release --skip=publish` succeeds with validation enabled. Keep the current Homebrew formula interface for this migration; switching to the replacement cask requires a separate distribution decision.