Skip to content

urmzd/dotfiles / dot_agents/skills/sync-release

sync-release

Unverified

Owns release-pipeline conventions: sr.yaml schema, the sr CLI verbs (init/plan/prepare/ release) and urmzd/sr action, typed publishers (cargo/npm/pypi/docker/go/custom), monorepo workspace discovery, version_files/stage_files mapping, and post-release patterns. Language-specific build targets live in scaffold-rust, scaffold-go, scaffold-python, scaffold-node. Use when writing or editing sr.yaml, choosing a publisher, or wiring the sr action. Do NOT use for GitHub Actions workflow file structure, ci.yml/release.yml naming, concurrency, workflow_call, or the App-token checkout; use setup-ci for those.

Release Workflow

Universal release conventions. For language-specific build matrices, publish steps, and sr.yaml templates, see the corresponding scaffold-* skill.

Release Philosophy

  • Target accessibility: build for multiple platforms (Linux, macOS, Windows)
  • Users should be able to install with one command (install.sh)
  • GitHub Actions where applicable (sr, fsrc, teasr expose actions)
  • Every release automatically updates changelog, creates GitHub release, uploads artifacts

sr.yaml Standard Config

Canonical filename: sr.yaml (not .urmzd.sr.yml). Use sr init to generate a fully-commented config.

git:
  tag_prefix: "v"
  floating_tag: true
  sign_tags: false
  v0_protection: true

commit:
  types:
    minor:
      - feat
    patch:
      - fix
      - perf
      - refactor
    none:
      - docs
      - revert
      - chore
      - ci
      - test
      - build
      - style

changelog:
  file: CHANGELOG.md

channels:
  default: stable
  branch: main
  content:
    - name: stable

packages:
  - path: .
    version_files: []
    stage_files: []
    # publish:
    #   type: cargo       # or npm, pypi, docker, go, custom
    #   workspace: true   # iterate workspace members

Version Files

version_files (bumped by sr) are language-specific. See the relevant scaffold-<lang> skill for the canonical values for that ecosystem. sr auto-discovers workspace members where the ecosystem supports it (Cargo, uv, pnpm/npm).

Lock files (sr v9+)

When sr bumps a manifest, it also rewrites the matching lock file and stages it in the same chore(release) commit. The rewrite edits the lock as TOML/JSON: no cargo update, uv lock, poetry lock or npm install, and no network access.

LockWhat sr rewrites
Cargo.lock[[package]] entries with no source (workspace crates)
uv.lock[[package]] entries whose source is editable, virtual or directory
poetry.lock[[package]] entries with [package.source] type = "directory"
package-lock.jsonroot version plus packages entries for workspace members
pnpm-lock.yaml, yarn.locknothing (they store no member versions); staged unchanged

Registry entries and hashes are never touched. Intra-workspace requirements also follow the bump: Cargo path deps that carry a version, and npm sibling ranges such as ^1.0.0.

  • Discovery. A lock is synced only when it is discovered from a bumped manifest: sr looks for the ecosystem's lock names in the manifest's directory and each parent up to the repo root. The manifest must therefore be bumped (listed in version_files or auto-discovered as a workspace member), and the lock must sit beside it or in an ancestor directory. A lock anywhere else is not synced.
  • stage_files. It only stages paths; it never syncs them. Discovered locks are staged automatically, so listing them in stage_files is redundant. Keep stage_files for other generated files that must ride in the release commit.
  • Format pins. Each rewrite is pinned to a verified format (Cargo.lock v4, uv.lock v1 rev 2, poetry.lock 2.x, package-lock.json v3). A newer format fails the release instead of committing a half-updated lock: upgrade sr or relock with an older tool.
  • No post-release lock commit. Do not add a CI step that re-runs cargo update -w, uv lock, npm install --package-lock-only or similar after sr prepare/sr release and commits the result. sr's release commit already carries the synced lock.

CLI Commands

Three verbs form the release pipeline: plan previews, prepare writes bumped files to disk, release reconciles everything.

sr init         Create sr.yaml (use --merge to add new fields non-destructively)
sr plan         Terraform-style diff: planned version, tag, artifacts, publish targets
sr prepare      Bump version files + write changelog (no commit/tag/push -- for CI build steps between plan and release)
sr release      Reconcile: commit, tag, push, GitHub release, upload artifacts, publish
sr config       Validate and display resolved configuration
sr migrate      Show the full version-by-version migration guide
sr completions  Generate shell completions
sr update       Update sr to the latest version

AI-assisted commit, PR, and review authoring live in dedicated agent skills (ship, pr, review). The sr CLI is release-engineering only.

Upgrading sr

Run sr migrate for the full breaking-change guide. v8 turned sr into a release-state reconciler: shell hooks removed (builds live in CI), typed publishers (cargo/npm/docker/pypi/go/custom) replace hooks.post_release, literal paths replace globs in artifacts/stage_files, and monorepos collapse to one global version (no more -p <pkg>). v9 made lock sync mandatory (see Lock files); action inputs, outputs, CLI verbs and the sr.yaml schema are unchanged. From v9.0.1, publisher output (cargo publish, npm publish, uv publish, etc.) goes to stderr so the action's JSON outputs stay parseable.

Release Pipeline

push to main
  → ci.yml (fmt → lint → test)
  → release.yml:
      fsrc (sync embedded sources) [if markers exist]
      → sr release (bump + lock sync → changelog → commit → tag → GitHub release)
      → build / publish [language and registry specific; see scaffold-* skills]
      → teasr (post-release demo capture) [if teasr.toml exists]

sr Action Usage

- uses: urmzd/sr@v9
  id: sr
  with:
    github-token: ${{ steps.app-token.outputs.token }}

Inputs mode (plan/prepare/release, default release), dry-run (deprecated alias for mode: plan), github-token (default github.token), git-user-name (default sr-releaser[bot]), git-user-email, artifacts (literal paths, space-separated), channel, prerelease, stage-files (literal paths), sign-tags, draft, sha256 (checksum verification).

Outputs released (bool), version, previous-version, tag, bump (major/minor/patch), floating-tag, commit-count, json (full release metadata).

Post-Release Patterns

  • Demo capture teasr then commit generated assets
  • File embedding fsrc then commit

Apply only what the repo declares.

Typed Publishers

sr runs registry uploads via publish: on each package, no shell hooks. Each publisher queries its registry to skip already-published versions, so re-runs are idempotent.

packages:
  - path: .
    publish:
      type: cargo        # or npm, pypi, docker, go, custom
      workspace: true    # iterate workspace members in declaration order
TypeCommandNotes
cargocargo publish (per workspace member when workspace: true)Reads [workspace].members
npmnpm publish / pnpm publish -r / yarn workspaces foreachAuto-detects tool by lockfile; set access: public for scoped packages
pypiuv publishworkspace: true iterates [tool.uv.workspace].members
dockerdocker buildx build --pushConfigure image, platforms, dockerfile
goNo-op (Go modules publish via git tag)sr already cuts the tag
customYour command; optional check to skip when already publishedReceives SR_VERSION / SR_TAG env

Pre-release validation

Run tests, lints, and pre-flight scripts as ordinary CI steps before sr release. Fail the job there, not inside sr.

Build strategy

sr release does not compile. Pick the shape that matches what you ship:

ScenarioCI shapeartifacts in sr.yaml
Pure library (no binaries)single job: sr releasen/a
Single-platform binarybuild then sr release in one jobliteral path(s) to the built binary
Multi-platform binariessr prepare → build matrix → sr release (three jobs, artifacts flow via actions/upload-artifact)literal paths for every target

Multi-platform: sr prepare bumps version files and syncs lock files so matrix builds embed the right version (carry the bumped manifests and locks to the build jobs together); the final release job downloads all matrix artifacts, commits, tags, uploads, and publishes.

Monorepo Support

One global version across all packages: sr auto-discovers workspace members from [workspace].members (Cargo), [tool.uv.workspace].members (uv), or pnpm-workspace.yaml / package.json workspaces. Independent per-package versioning is no longer supported; use separate repos if packages must diverge.

writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 319kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall