Neva Release Skill

Overview

Use this skill to prepare a monthly release for nevalang/neva with consistent notes and assets. Default output is a draft GitHub release, not immediate publication.

Core Tools

• gh (release + PR metadata)
• git (range and branch state)
• make (artifact build)
• shasum (asset checksums)
• GitHub web UI (optional final review/publish)

Workflow

1. Confirm version bump policy before tagging.
   • If the bump is ambiguous, ask explicitly: patch or minor.
   • Default to patch for internal-only changes (CI, docs, lint, infra, refactors without user-facing behavior change).
   • Use minor for user-facing language/stdlib/CLI features or meaningful behavior additions.
   • major is out of routine flow; always ask.
2. Sync to clean, up-to-date main state.
   • git fetch origin --tags --prune
   • ensure working tree is clean
   • ensure build source equals origin/main (or use a clean worktree from it)
3. Read release style from recent history.
   • inspect 1-2 previous release notes via gh release view ... --json body,publishedAt
   • do not download previous binary assets
4. Collect merged PRs in the release window.
   • determine range from previous tag (for example vX.Y.Z..origin/main)
   • gather merged PR numbers and read each PR description (gh pr view)
5. Bump repository version references.
   • update pkg/version.go to the next release version without the v prefix
   • update checked-in Neva manifests and examples that pin the current language version (std/neva.yml, examples/neva.yml, benchmarks/neva.yml, e2e/**/neva.yml, and internal test manifests)
   • update docs and tests that show or assert the current version
   • update generated headers only when they embed the current version string
   • run rg "v?X\\.Y\\.Z" for the previous version and inspect every remaining hit; only leave historical changelog/release-note references intentionally
6. Draft release notes.
   • keep style concise and factual
   • include: theme/title, summary, key sections, related PR list, full changelog compare link
   • if changes are mostly internal, say that directly
   • include examples for user-facing changes:
     • CLI changes: add at least one command snippet showing new command/flag usage
     • language changes: add at least one Nevalang code snippet
   • keep examples small; full compilable wrappers are optional
7. Build assets locally from clean main state.
   • make build
   • verify expected platform binaries are present
   • compute checksums with shasum -a 256
8. Create draft release with assets.
   • gh release create <tag> <assets...> --target main --title <tag> --notes-file <file> --draft
   • verify metadata and uploaded assets via gh release view <tag> --json ...
9. Report back.
   • release URL
   • included PRs
   • asset names and checksums
   • note whether release remains draft (default)

Guardrails

• Do not publish the release unless explicitly requested.
• Do not invent release claims not supported by merged PR descriptions.
• Prefer gh over ad-hoc API calls where possible.
• Keep the skill lightweight; avoid scripts unless explicitly requested.
• Do not pad examples with unnecessary boilerplate (def Main, imports, full component wrappers) when a focused snippet is enough.

Example Quality Check (Nevalang)

When release notes include Nevalang snippets, they must be concise but real.

1. Keep snippets minimal.
   • Prefer showing only the relevant node declarations + --- + connections when that explains the change.
   • Full compile-ready files are optional.
2. Keep snippets language-true.
   • syntax must match current grammar (internal/compiler/parser/neva.g4)
   • semantics should follow project invariants from AGENTS.md (for example Main port shape, chaining rules, [*] bypass form)
3. Sanity-check against real code.
   • compare syntax patterns with 1-2 existing examples (examples/**/*.neva)
   • if confidence is low, rewrite to a simpler canonical form before publishing