Skip to content

RELEASE.md

Latest commit

 

History

History
140 lines (104 loc) · 6.41 KB

RELEASE.md

File metadata and controls

140 lines (104 loc) · 6.41 KB
Raw

Release Operations

This document catalogues the manual steps and prerequisites for the release workflow. The automated flow lives in .github/workflows/. Each automatable publish channel is gated on a repository variable — when the variable is true and the corresponding secret is configured, publishing is automatic. Otherwise the channel is skipped and the steps below serve as the manual fallback. Zed is the exception: it has no automated path at all and always requires a pull request against the registry.

Prerequisites (one-time setup)

GitHub

  • RELEASE_PR_TOKEN secret: a Personal Access Token with repo contents-write. Used by release-pr.yml to push the bump commit to dev and open the release PR. The default GITHUB_TOKEN is avoided because PRs opened with it don't trigger CI.
  • dev branch as the default branch. Feature work lands on dev; only release PRs go dev → main.
  • Branch protection on main (PR + required CI) and dev (required CI on PRs).

VS Code Marketplace

  • A publisher account named synthpunk on the VS Code Marketplace.
  • VS_MARKETPLACE_TOKEN secret: a Personal Access Token from the Marketplace publisher dashboard.
  • PUBLISH_VSCODE variable set to true to enable auto-publishing.

OpenVSX

  • An account on OpenVSX.
  • OVSX_TOKEN secret: an access token from your OpenVSX settings.
  • PUBLISH_OPENVSX variable set to true to enable auto-publishing.

Zed

Zed has no publish CLI and no token-based channel — the registry is a git repository, and every version ships as a pull request against it. Zed is never automated by release.yml; it is always a manual follow-up.

  • A fork of zed-industries/extensions, cloned locally (assumed at ../extensions below) with an upstream remote pointing at the canonical repo.
  • Nothing else — no account, secret, or repository variable is involved.

The registry registers the extension as a git submodule of this repository plus an entry in its extensions.toml. Because our manifest lives at themes/zed/ rather than the repository root, that entry carries a path field:

[synthpunk-theme]
submodule = "extensions/synthpunk-theme"
path = "themes/zed"
version = "X.Y.Z"

Two constraints are enforced by the registry's CI and are easy to trip over:

  • The submodule must be named and located at extensions/synthpunk-theme — matching the id in themes/zed/extension.toml, not the name of this repository — and must use an https:// URL.
  • The license is read from the extension directory only, never the repository root. themes/zed/LICENSE is generated by bun run build for exactly this reason; do not delete it.

The extension ID is permanent. The registry rejects any PR that both adds and removes an ID, so synthpunk-theme cannot be renamed after the first submission — only the display name in extension.toml can change.

Neovim (synthpunk.nvim)

  • An empty slowdini/synthpunk.nvim repository on GitHub.
  • SYNTHPUNK_NVIM_DEPLOY_KEY secret: an SSH deploy key with write access to slowdini/synthpunk.nvim.
  • PUBLISH_NVIM variable set to true to enable auto-publishing.

Manual publishing (when a channel is not automated)

If a publish variable is not set (or the secret is missing), the corresponding job is skipped. Run these commands manually after the GitHub release is created:

VS Code Marketplace

git checkout vX.Y.Z
cd themes/vscode
npx @vscode/vsce publish -p <VS_MARKETPLACE_TOKEN>

OpenVSX

git checkout vX.Y.Z
cd themes/vscode
npx @vscode/vsce package -o synthpunk-vX.Y.Z.vsix
npx ovsx publish synthpunk-vX.Y.Z.vsix -p <OVSX_TOKEN>

Zed

Always manual. Both recipes assume the fork is at ../extensions with an upstream remote, and that vX.Y.Z has already been tagged here.

First submission (one time only):

cd ../extensions
git fetch upstream
git checkout -b add-synthpunk-theme upstream/main
git submodule add https://github.com/slowdini/synthpunk.git extensions/synthpunk-theme
git -C extensions/synthpunk-theme checkout vX.Y.Z
# add the [synthpunk-theme] entry shown above to extensions.toml
pnpm install && pnpm sort-extensions
git add extensions.toml .gitmodules extensions/synthpunk-theme
git commit -m "Add synthpunk theme"
git push -u origin add-synthpunk-theme

Then open a PR against zed-industries/extensions titled Add synthpunk theme. Test the extension locally first (Zed → Extensions → Install Dev Extension → select themes/zed/); their CONTRIBUTING.md states that untested submissions are closed.

Subsequent versions:

cd ../extensions
git fetch upstream
git checkout -b update-synthpunk-vX.Y.Z upstream/main
git submodule update --init --recursive extensions/synthpunk-theme
git -C extensions/synthpunk-theme fetch --tags
git -C extensions/synthpunk-theme checkout vX.Y.Z
# bump `version` under [synthpunk-theme] in extensions.toml to X.Y.Z
pnpm install && pnpm sort-extensions
git add extensions.toml .gitmodules extensions/synthpunk-theme
git commit -m "Update synthpunk-theme to vX.Y.Z"
git push -u origin update-synthpunk-vX.Y.Z

The version in extensions.toml must exactly match the version in themes/zed/extension.toml at the pinned commit, and must not decrease.

Neovim (synthpunk.nvim)

git checkout vX.Y.Z
git clone git@github.com:slowdini/synthpunk.nvim.git /tmp/synthpunk.nvim
cd /tmp/synthpunk.nvim
rm -rf -- */
cp -r /path/to/synthpunk/themes/neovim/* .
git add -A
git commit -m "chore: release vX.Y.Z"
git tag vX.Y.Z
git push origin main
git push origin vX.Y.Z

Release flow summary

  1. Trigger: Actions → "Release PR" workflow → Run with version X.Y.Z.
  2. Bump: release-pr.yml bumps all manifests, commits to dev, opens dev → main PR.
  3. Review: Edit the PR body with release notes, merge into main.
  4. Auto-release: release.yml on push to main:
    • Tags vX.Y.Z, creates GitHub Release (notes from PR body or auto-generated).
    • Builds all themes, uploads Starship + WezTerm files to the release.
    • Builds VS Code VSIX, publishes to Marketplace/OpenVSX if configured.
    • Splits themes/neovim/ to slowdini/synthpunk.nvim if configured.
  5. Back-sync: Merge main back into dev.
  6. Zed: Open the PR against zed-industries/extensions by hand — see the Zed section above. This channel is never automated.