skillshare-release · diff
git:20260924.bf1226e to git:20261001.1fe668e
39 added, 89 removed. Audit A to A.
---
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`).
-
- 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
+ Prepare or review a skillshare release. An optional version argument is an explicit requested version, not permission to commit, merge, tag, push, or publish.
- - 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
-
- Run full test suite and code quality checks. Fix any failures before proceeding.
-
- ```bash
- make check # fmt-check + lint + test (builds binary first)
- ```
+ ### 1. Identify the release
- If tests fail: fix them, don't skip. Do not ask the user — fix and re-run.
+ 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`.
- ### Phase 2: Changelog
+ 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.
- Invoke `/changelog $VERSION` to generate the changelog entry.
+ 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.
- 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`)
+ #### Explicit version requests
- Review the output before proceeding.
+ 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.
- ### Phase 3: Release Notes Draft (Maintainer Only, Local by Default)
+ ```text
+ fix: correct sync behavior
- Check if running as maintainer:
- ```bash
- git config user.name # Should match "Willie" or maintainer identity
+ Release-As: 0.23.3
```
- **If maintainer**:
-
- 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`).
-
- 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.
-
- 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
-
- **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
+ 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.
- **If not maintainer**: Skip this phase.
+ 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.
- ### Phase 4: Version Bump
+ ### 2. Review the Release PR
- Update the version in `skills/skillshare/SKILL.md` frontmatter:
+ 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:
- ```yaml
- metadata:
- version: vX.Y.Z
+ ```bash
+ 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'
```
- 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.
+ 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.
- ```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
- ```
+ 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.
- Do NOT push yet — wait for user confirmation.
+ ### 3. Inspect the draft
- ### Phase 6: Draft Announcements
+ 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.
- Prepare two drafts for user review:
+ 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.
- 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.
+ ### 4. Optional local notes and announcements
- 2. **Social media post** — 2-3 sentences max, casual tone, mention the version and 1-2 headline features. No hashtag spam.
+ 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.
- **Tone**: short, direct. Don't oversell. The user will edit before posting.
+ Draft announcements only when requested. Describe user-visible behavior, add examples and migration guidance, and avoid internal implementation details.
- ### Phase 7: Present & Confirm
+ ### 5. Publish only when authorized
- 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
+ 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.
- Wait for user approval before pushing:
- ```bash
- git push origin HEAD --tags
- ```
+ 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.
- ## Rules
+ ## Report
- 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.