* feat: add Nix flake and stop self-upgrade of Nix-store installs Add flake.nix with packages, overlays.default, checks and a formatter, building nix/package.nix with the unit tests in the Nix sandbox. The version comes from the Release Please manifest, so releases need no Nix edit. A Nix workflow runs `nix flake check` on non-docs changes. `skillshare upgrade` now detects binaries under /nix/store/ and prints `nix profile upgrade skillshare` instead of replacing a read-only store path; update notices and doctor suggest the same command. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(upgrade): give Nix installs the right update path everywhere The first flake commit sent every /nix/store binary to `nix profile upgrade`, failed a plain `skillshare upgrade` with exit 1 even when the CLI was current, and left the dashboard with a generic 500. - Tell `nix profile` installs (the profile manifest lists the store path) from NixOS, Home Manager and overlay installs, which are told to update their configuration and rebuild. Detection lives in one helper shared by the update notice, doctor, upgrade and the dashboard. - `upgrade` on Nix reports "already up to date" or prints the hint and exits 0; the built-in skill still updates. - The dashboard runs the upgrade so the skill updates, then answers 409 `upgrade.nix` with the command when a newer CLI waits on Nix. The UI shows localized text for it in all 11 locales. - Installs skip the unit tests; the flake's checks enable them. postPatch lowers only the go directive's patch version and fails evaluation with a clear message when go.mod needs a newer Go minor. CI also builds the package on macOS. - Docs, translations, the built-in skill reference and the release topic describe the new behaviour. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
10 KiB
Changelog and Release
Use when writing a version changelog, release notes, version bump, tag, announcement, or full release.
Authorization Boundary
A changelog-only request does not authorize commits, tags, pushes, publication, or version bumps. A full release request authorizes preparation and explicitly included local Git actions, but pushing or publishing still requires user confirmation. Never mix unrelated working-tree changes into staging.
Changelog
- Determine the range from the requested version or tags, then collect commits with
git log <previous>..<current> --no-merges. - Read the newest two or three
CHANGELOG.mdentries and follow the current style. - Categorize user-visible features, bug fixes, performance improvements, and breaking changes. Exclude test-only, CI-only, pure refactoring, and internal implementation noise.
- Verify every feature claim against source and never fabricate links.
- Add the entry at the top of
CHANGELOG.mdand insert the same release entry after the frontmatter/intro separator inwebsite/src/pages/changelog.md.
Version headings use [X.Y.Z] without a v prefix and include the date. Feature bullets use a bold name, an em dash, and a real usage example. Create only sections that contain content.
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.
- A push to
mainruns 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. - Review the proposed version and user-facing notes on the Release PR branch.
python3 scripts/release/release.py syncnormalizes the heading and syncs the files;checkverifies their agreement. Run these helpers inside the devcontainer. Bot PR creation and updates usingGITHUB_TOKENmay leave PR CI awaiting the maintainer's native Approve workflows to run prompt. - 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. The ordinary push run of Test skips that merge commit, because this gate already tests it; the Release PR's own runs still execute as required checks.
- 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 aGITHUB_TOKENtag push triggering another workflow. - 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.
- 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 and Website Pages. Release Docker images and the website use the same tag commit. Draft tags never publish Docker images, update the tap or deploy the website; pushes to
maindo not deploy it either.
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, and Website Pages can be dispatched with a tag or branch to redeploy or ship a docs-only fix. 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.
- Use
git statusto separate task-owned changes from existing work. - Run the complete
make checkinside the devcontainer and never skip a failure.
Then:
- Bring the documentation up to date with the pending range
<latest published tag>..origin/main, following thedocumentationtopic: check each user-visible feature, fix and breaking change against the command pages, guides, troubleshooting, built-in skill and README in every locale, then build the whole website inside the devcontainer withnpm run buildinwebsite/, as the Website Pages workflow does. For a minor or major release, also rewrite theLatestcallout inREADME.mdand every translated README, and add the range's contributors to theREADME.mdContributors section: authors of the issues and PRs it references, commit authors andCo-authored-bytrailers, other than the maintainer and anyone already listed. Documentation fixes land onmain, so finish them before editing the Release PR. A push tomainwhose commits change the generated notes, such as a newfeatorfix, regenerates the Release PR and discards edits made on its branch;docscommits leave it as it is. - Generate and review the changelog.
- Write the GitHub release body to
specs/RELEASE_NOTES_<version>.md, following the newest one. After the draft is built, apply it withgh release edit vX.Y.Z --notes-file specs/RELEASE_NOTES_<version>.md; Publish Release keeps it, but rebuilding the draft regenerates the body fromCHANGELOG.md. - Review the manifest's proposed version and synchronize the Release PR files; do not perform a separate manual version bump.
- Commit review edits or merge the Release PR only when explicitly requested. Stage only task-owned files. The automation owns release tagging after verification.
- Draft concise GitHub release notes and a social announcement.
- Present tests, diffs, local-only artifacts, and commit/tag state; obtain confirmation before pushing or publishing.
Release notes are local maintainer artifacts by default. Never force-add an ignored file unless explicitly requested. Never infer authorization for credentials, registry login, or external publication.
Nix Flake
flake.nix builds nix/package.nix, which reads its version from the Release Please manifest, so releases need no Nix edit. A github:runkids/skillshare install builds main and reports the latest release version.
Installs skip the unit tests; only the flake's checks run them. The Nix workflow runs nix flake check (build plus unit tests in the sandbox) on Linux and builds the package on macOS for every non-docs change. Two failures need a hand edit:
- A hash mismatch after a
go.sumchange: put the log'sgot: sha256-...value intovendorHash. go.modrequiring a Go minor version newer than the locked nixpkgs ships fails evaluation with a message saying so: runnix flake update. Newer patch versions need nothing, becausepostPatchlowers thegodirective to the toolchain's version.
The devcontainer has no Nix, so reproduce Nix failures in a throwaway nixos/nix container, never on the host: docker run --rm --privileged -v "$PWD":/src -w /src nixos/nix nix --extra-experimental-features 'nix-command flakes' build --option sandbox true -L path:/src.
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.