rojo/.cursor/commands/release.md

/release - Version Bump and Tag Release

Bump the project version, update the changelog, commit, push, and tag a new release.

The user must provide the new version string (e.g. 8.0.1). If not provided, ask for it before proceeding.

---

Step 1: Pre-Flight — Submodule Check

Run these two commands and inspect the output:

git submodule status

git submodule foreach "git status --short"

Verify ALL submodules are clean:

• No submodule prefixed with + (dirty) or - (uninitialized) in git submodule status
• No uncommitted changes in any submodule from git submodule foreach

If any submodule is dirty or uninitialized, STOP immediately. Report which submodules have issues and do not proceed until the user resolves them.

Ignore rbx-dom/aftman.toml — it references the Atlas version but is not part of the release process.

---

Step 2: Version Bump

Replace the old version with the new version in each of these files:

File	What to change
Cargo.toml	version = "X.Y.Z" (line 3)
plugin/Version.txt	Entire file content — must match Cargo.toml exactly (enforced by build.rs)

Do NOT manually edit Cargo.lock. It is auto-updated in the next step.

Note: rokit.toml does NOT contain atlas — the tool builds from source and should never self-reference a version that may not be released yet.

After editing the three files above, run:

cargo check

This does two things:

1. Auto-updates Cargo.lock with the new version
2. Validates that plugin/Version.txt matches Cargo.toml (build.rs assertion — build will fail if mismatched)

If cargo check fails, fix the issue before continuing.

---

Step 3: Update CHANGELOG.md

3a. Gather commit history

Run this to get all commits since the previous version tag (replace vOLD with the previous tag):

git log --oneline vOLD..HEAD

3b. Write the release section

Insert a new version section between ## Unreleased and the previous version's header. Format:

## Unreleased

## [X.Y.Z] (Month Dth, Year)

* Summary of change 1
* Summary of change 2
* ...

[X.Y.Z]: https://github.com/UserGeneratedLLC/rojo/releases/tag/vX.Y.Z

Guidelines for writing entries:

• Group related commits into single bullet points (don't list every commit separately)
• Write user-facing descriptions, not raw commit messages
• Use present tense ("Add", "Fix", "Improve", not "Added", "Fixed", "Improved")
• Omit internal-only changes (CI tweaks, test refactors, snapshot updates) unless they affect behavior
• Keep link definitions in ascending numeric order (per repo convention)

3c. Include a git summary

After the bullet points, add a collapsible section with the raw commit log so readers can see full detail:

<details>
<summary>Full commit log</summary>

- `abc1234` Commit message one
- `def5678` Commit message two
- ...

</details>

---

Step 4: Commit, Push, Tag, Push Tag

Run these sequentially:

git add Cargo.toml Cargo.lock plugin/Version.txt CHANGELOG.md

git commit -m "$(cat <<'EOF'
X.Y.Z

- Key change 1
- Key change 2
- ...
EOF
)"

Commit message guidelines:

• First line: just the version number
• Body: concise bullet list of the most important changes since the last tag (derived from the changelog entries written in step 3)
• Distill to the highlights — not a copy of the full changelog

git push

git tag vX.Y.Z

git push origin vX.Y.Z

The tag push triggers .github/workflows/release.yml which creates a draft GitHub release and builds artifacts for all platforms.

---

All Versioned Files (Reference)

File	Role	Updated by
Cargo.toml	Crate version (source of truth)	Manual edit
Cargo.lock	Lockfile version	cargo check (automatic)
plugin/Version.txt	Plugin version, validated at build time	Manual edit
CHANGELOG.md	Release notes	Manual edit