revize release skills #836
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,128 @@ | ||
| --- | ||
| name: release | ||
| description: Orchestrate a full stellar-contracts release end-to-end (READMEs, version bump, audit report, Wizard, docs site, release branch, release notes) with a confirmation gate before every step | ||
| user_invocable: true | ||
| --- | ||
|
|
||
| # Release Orchestrator | ||
|
|
||
| ## Context | ||
|
|
||
| Publishing a new release of stellar-contracts touches several repos and services, not just this one. This skill walks the full checklist step by step. It does NOT execute everything in one go — every step passes through the Gate Pattern below. | ||
|
|
||
| Repos involved (adjust paths if the user's checkout differs): | ||
|
|
||
| | Repo | Local path | Role | | ||
| | ------------------ | ---------------------------------------------- | ------------------------------------------------ | | ||
| | stellar-contracts | `~/Developer/OpenZeppelin/stellar-contracts` | The library being released | | ||
| | contracts-wizard | `~/Developer/OpenZeppelin/contracts-wizard` | Wizard UI (`packages/core/stellar`) | | ||
| | docs | `~/Developer/OpenZeppelin/docs` | docs.openzeppelin.com content (`content/stellar-contracts/`) | | ||
|
|
||
| Companion skills this orchestrator delegates to. Each lives in the repo it operates on — prefer | ||
| the user's local checkout of that repo; fall back to fetching from GitHub: | ||
|
|
||
| | Step | Skill (path within its repo) | GitHub | | ||
| | --------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | ||
| | Steps 1–2 | `.claude/commands/version-bump.md` (this repo) | https://github.com/OpenZeppelin/stellar-contracts/blob/main/.claude/commands/version-bump.md | | ||
| | Step 4 | contracts-wizard: `.claude/skills/stellar-release-update/SKILL.md` | https://github.com/OpenZeppelin/contracts-wizard/blob/master/.claude/skills/stellar-release-update/SKILL.md | | ||
| | Step 5 | docs: `.claude/skills/update-stellar-docs.md` | https://github.com/OpenZeppelin/docs/blob/main/.claude/skills/update-stellar-docs.md | | ||
|
|
||
| ## The Gate Pattern (mandatory) | ||
|
|
||
| For EVERY step below, follow this three-phase gate. Never merge phases, never skip ahead to implementation. | ||
|
|
||
| 1. **Relevance check** — First determine whether the step is needed at all. Gather the evidence (diff the release range, check for open PRs, look for new modules, etc.), present a short summary of what you found, and ask the user: *"Step N is [needed / probably not needed] because <evidence>. Should I proceed, or skip it?"* | ||
| 2. **Plan** — If proceeding, inspect the affected code/files and present the big picture of what would change: which files, what kind of edits, anything risky or ambiguous. Do NOT make any changes yet. Ask for confirmation on the plan. | ||
| 3. **Apply** — Only after the user confirms the plan, implement it. Then report what was done and show the updated checklist before moving to the next step's gate. | ||
|
|
||
| Between steps, re-print the checklist with current status (`[x]` done, `[~]` skipped with reason, `[ ]` pending) so the user always sees where the release stands. | ||
|
|
||
| ## Inputs | ||
|
|
||
| At the start, ask the user for: | ||
|
|
||
| 1. The **new version number** (e.g., `0.9.0`) and whether it is a final release or an RC | ||
| 2. The **previous release tag** to diff against (e.g., `v0.8.0`) — verify it exists with `git tag` | ||
| 3. Where the **final audit report PDF** is (a local path), or "not available yet" | ||
|
|
||
| Then run a preflight in stellar-contracts: `git status` is clean, `git fetch --tags` done, and note which branch you're on. Compute the release diff once (`git log <prev_tag>..HEAD --oneline`, `git diff <prev_tag>..HEAD --stat`) and reuse it as evidence in the gates below. | ||
|
|
||
| ## Checklist (tracking template) | ||
|
|
||
| ``` | ||
|
Contributor
There was a problem hiding this comment. 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win Add a language to the checklist code fence. The unlabeled fence triggers markdownlint MD040. Use 🧰 Tools🪛 markdownlint-cli2 (0.23.2)[warning] 52-52: Fenced code blocks should have a language specified (MD040, fenced-code-language) 🤖 Prompt for AI AgentsSource: Linters/SAST tools |
||
| [ ] 1. Review GH READMEs and update if necessary | ||
| [ ] 2. Update `version` in Cargo.toml + `cargo build` to refresh Cargo.lock | ||
| [ ] 3. Upload final audit report to /audits (renamed to match pattern) | ||
| [ ] 4. Merge Wizard PR if any | ||
| [ ] 5. docs.openzeppelin.com — new module docs + version update | ||
| [ ] 6. Create `release-v<X.Y.Z>` branch (triggers Netlify publish webhook) | ||
| [ ] 7. Release notes mentioning all contributors (optional) | ||
| [ ] 8. Skill maintenance sweep — update the release skills themselves | ||
| ``` | ||
|
|
||
| ## Steps | ||
|
|
||
| ### 1 + 2. READMEs, version bump, build | ||
|
|
||
| These two checklist items are already covered by the `version-bump` skill in this repo. | ||
|
|
||
| - **Relevance check**: always needed for a release — but confirm the version number one more time before starting. | ||
| - **Plan / Apply**: invoke the `version-bump` skill (`.claude/commands/version-bump.md`) and follow it. Keep the Gate Pattern inside it too: present the list of README edits it wants to make before making them. | ||
| - Done when: `cargo build` passes, `Cargo.lock` reflects the new version, and `grep -rn '"=OLD_VERSION"' --include='*.md' --include='Cargo.toml'` comes back clean. | ||
|
Comment on lines
+65
to
+71
Contributor
There was a problem hiding this comment. 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win Enforce one complete safety gate for every version bump. The release command delegates to
📍 Affects 2 files
🤖 Prompt for AI Agents |
||
|
|
||
| ### 3. Audit report | ||
|
|
||
| - **Relevance check**: skip (with `[~]`) if the user said the report isn't available yet, or if this is an RC that wasn't audited. Ask which audit this release corresponds to. | ||
| - **Plan**: look at `audits/` to confirm the current naming pattern. As of writing it is: | ||
| `Stellar Contracts Library v<X.Y.Z> Audit.pdf` (with a `Re-Audit` variant for follow-ups, e.g. `Stellar Contracts Library v0.5.0 Re-Audit.pdf`). Show the user the exact target filename before copying. | ||
| - **Apply**: copy the PDF from the user-provided path into `audits/` under the confirmed name. Verify with `ls audits/`. | ||
|
|
||
| ### 4. Wizard PR | ||
|
|
||
| - **Relevance check**: two things to check, in order: | ||
| 1. Is there already an open Wizard PR for this release? Check with: | ||
| `gh pr list --repo OpenZeppelin/contracts-wizard --state open --search "stellar"` | ||
| 2. If no PR exists — does this release even need Wizard changes? Scan the release diff for changes to public traits, function signatures, or new user-facing contracts that the Wizard generates code for (`packages/core/stellar` in contracts-wizard). Internal-only changes need no Wizard update. | ||
| - **Plan**: | ||
| - If an open PR exists: summarize the PR (title, files touched, CI status) and ask whether to merge it now (`gh pr merge`). Merging is outward-facing — never merge without explicit confirmation. | ||
| - If no PR exists but changes are needed: follow the wizard sync skill (`.claude/skills/stellar-release-update/SKILL.md` in the contracts-wizard repo — see the companion table). Present its upstream-change analysis and update plan as the gate before touching wizard code. | ||
| - **Apply**: merge the PR, or implement the wizard changes and open a PR, per the confirmed plan. | ||
|
Comment on lines
+82
to
+89
Contributor
There was a problem hiding this comment. 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- target file metadata ---'
wc -l .claude/commands/release.md
printf '%s\n' '--- target section ---'
sed -n '1,150p' .claude/commands/release.md
printf '%s\n' '--- related references ---'
rg -n -i --glob '!node_modules' --glob '!dist' \
'Wizard PR|contracts-wizard|gh pr list|stellar-release-update|release version|release branch' \
.claude README.md 2>/dev/null || true
printf '%s\n' '--- tracked candidate files ---'
git ls-files | rg '(^|/)(release\.md|SKILL\.md)$|contracts-wizard|wizard' | head -200Repository: OpenZeppelin/stellar-contracts Length of output: 14151 🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- gh availability ---'
command -v gh || true
printf '%s\n' '--- broad Wizard PR search ---'
if command -v gh >/dev/null 2>&1; then
gh pr list \
--repo OpenZeppelin/contracts-wizard \
--state open \
--search "stellar" \
--limit 100 \
--json number,title,headRefName,baseRefName,url,files,statusCheckRollup
else
printf '%s\n' 'gh is unavailable'
fi
printf '%s\n' '--- Wizard sync skill ---'
if command -v gh >/dev/null 2>&1; then
gh api repos/OpenZeppelin/contracts-wizard/contents/.claude/skills/stellar-release-update/SKILL.md \
--jq '.content' | base64 --decode | sed -n '1,240p'
else
printf '%s\n' 'gh is unavailable'
fiRepository: OpenZeppelin/stellar-contracts Length of output: 50387 Match the Wizard PR to this release before merging. The broad search returns multiple open PRs. Match the PR by release version or branch, then verify its files and CI status before offering 🤖 Prompt for AI Agents |
||
|
|
||
| ### 5. docs.openzeppelin.com | ||
|
|
||
| > Note: the old checklist item "update version in `docs/antora.yml`" is obsolete — Antora docs were removed from this repo (PR #483, Oct 2025). Docs now live in the `docs` repo as `.mdx` under `content/stellar-contracts/`, with sidebar navigation in `src/navigation/stellar.json`. | ||
|
|
||
| - **Relevance check**: from the release diff, list new crates/modules/extensions and public API changes (breaking renames, removed APIs). If there are none, docs likely only need a version-reference sweep — say so and ask. | ||
| - **Plan / Apply**: follow the docs update skill (`.claude/skills/update-stellar-docs.md` in the docs repo — see the companion table) covering new pages, breaking-change sweeps, navigation registration, `pnpm run build` + `pnpm run check`. Present its Step-3 plan (which pages get created/edited) as the gate before writing. Docs changes go up as a PR to the docs repo — do not push directly. | ||
|
|
||
| ### 6. Release branch | ||
|
|
||
| - **Relevance check**: confirm with the user that steps 1–5 are in the desired state and merged to `main`, and that they want to publish now. Creating this branch is the publish trigger — a `release-v<X.Y.Z>` branch pushed to origin fires a webhook to Netlify that publishes the new version to the docs site. Precedent: `origin/release-v0.2.0`, `origin/release-v0.3.0`, `origin/release-v0.7.2`. | ||
| - **Plan**: state the exact branch name (`release-v<X.Y.Z>`) and the commit it will point at (normally the tip of `main` after the release PR merged). | ||
| - **Apply**: `git checkout main && git pull`, `git checkout -b release-v<X.Y.Z>`, `git push origin release-v<X.Y.Z>`. This is outward-facing and hard to reverse — require an explicit "yes" before pushing. | ||
|
|
||
| ### 7. Release notes / contributors (optional) | ||
|
|
||
| - **Relevance check**: ask whether the user wants release notes drafted with a contributors section. This is optional per the checklist — skipping is fine. | ||
| - **Plan**: gather contributors for the release range: | ||
| - `git log <prev_tag>..<new_ref> --format='%an|%ae' | sort -u` for names | ||
| - prefer GitHub handles: `gh api repos/OpenZeppelin/stellar-contracts/compare/<prev_tag>...<new_ref> --jq '.commits[].author.login' | sort -u` | ||
| - Draft the notes: highlights, breaking changes, new modules, audit reference, and a "Contributors" section thanking each handle. Show the full draft. | ||
| - **Apply**: on confirmation, create/update the GitHub release draft: `gh release create v<X.Y.Z> --draft --title "v<X.Y.Z>" --notes-file <draft>` (or `gh release edit` if it exists). Leave it as a draft unless the user explicitly asks to publish. | ||
|
Comment on lines
+107
to
+111
Contributor
There was a problem hiding this comment. 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- file inventory ---'
git ls-files '.claude/commands/release.md' '.claude/commands' '.github' 'README.md' | sed -n '1,160p'
printf '%s\n' '--- release.md size and outline ---'
wc -l .claude/commands/release.md
if command -v ast-grep >/dev/null 2>&1; then
ast-grep outline .claude/commands/release.md
fi
printf '%s\n' '--- release.md lines 1-180 ---'
cat -n .claude/commands/release.md | sed -n '1,180p'
printf '%s\n' '--- relevant references ---'
rg -n -S --hidden --glob '!.git' \
'new_ref|<draft>|gh release (create|edit)|--target|prev_tag|release draft|confirmed release' \
.claude .github README.md 2>/dev/null || trueRepository: OpenZeppelin/stellar-contracts Length of output: 14760 🌐 Web query:
💡 Result: The GitHub CLI command gh release create is used to create a new release for a repository [1][2]. Regarding the specific behaviors you mentioned: --target The --target flag specifies the branch or full commit SHA that the release should be based on [1][3]. By default, if you do not provide a --target, the release is based on the default branch of the repository (e.g., main) [1][4]. Tag Creation If the git tag you specify in the command does not already exist, the GitHub CLI will automatically create one for you [1][2]. This automatic tag is created from the latest state of the target branch or commit SHA [1][5]. If the tag already exists, the release will be associated with that existing tag [6]. To fetch any newly created tags to your local repository after running the command, you should execute git fetch --tags origin [1][2]. --notes-file The -F or --notes-file flag allows you to read the release notes from a local file [1][2]. You can also pass "-" to this flag to read the release notes from standard input [2][5]. Example usage: gh release create v1.0.0 --target main -F release-notes.md In this example, the command creates a release for tag v1.0.0 based on the main branch, using the contents of release-notes.md as the release notes [1][2]. If v1.0.0 did not exist, it would be created automatically from the latest commit on main [1][5]. Citations:
Pin the GitHub release to the confirmed release commit. Define 🤖 Prompt for AI Agents |
||
|
|
||
| ### 8. Skill maintenance sweep | ||
|
|
||
| The release skills themselves rot: they hardcode versions, file paths, naming patterns, and repo conventions that any release can invalidate. (Past example: this skill's docs step originally said "update `docs/antora.yml`" — a file that had been deleted from the repo entirely.) This step keeps them honest. | ||
|
|
||
| - **Relevance check**: run this sweep on every release — it is cheap and drift compounds. Start from what happened during THIS release run: conventions that turned out different from what a skill claimed, files that had moved or been renamed, steps that were skipped as obsolete, and manual work you did that no skill covered. | ||
| - **Plan**: read each skill in the family and diff it against the reality you just observed: | ||
| - this repo: `.claude/commands/release.md` (this file) and `.claude/commands/version-bump.md` — paths, grep patterns, the audit filename pattern, the release-branch convention, line-number hints | ||
| - contracts-wizard: `.claude/skills/stellar-release-update/SKILL.md` — key-file table, commands, version-file locations | ||
| - docs repo: `.claude/skills/update-stellar-docs.md` — content paths, navigation file, build/check commands | ||
| - Dev3 repo: the pointer skills under `languages/soroban/` (`soroban-release`, `soroban-update-wizard`, `soroban-update-external-docs`) — canonical URLs, default-branch names, repo paths | ||
| Look specifically for: hardcoded version numbers or example tags that drifted, stale file paths, renamed traits/commands, changed default branches, changed naming patterns, and steps this run skipped or added. Present the proposed skill edits per file. | ||
| - **Apply**: make the confirmed edits in each repo's local checkout. Edits to skills in other repos go up as their own small PRs (or ride along with that repo's release-related PR) — state which route you took for each. | ||
|
Comment on lines
+118
to
+124
Contributor
There was a problem hiding this comment. 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift Add the Dev3 repository to the release inputs. The maintenance sweep requires files under 🤖 Prompt for AI Agents |
||
|
|
||
| ## Wrap-up | ||
|
|
||
| Print the final checklist with every item marked `[x]` or `[~] skipped: <reason>`, plus links to: the release PR(s), the Wizard PR, the docs PR, the pushed `release-v*` branch, the GitHub release draft, and any skill-maintenance PRs. Flag anything left for the user to do manually (e.g., publishing the draft release, verifying the Netlify deploy). | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Bind release evidence and publication to one immutable commit.
Line 48 computes evidence from the current
HEAD, but line 102 later pulls the currentmainand creates the publish branch. These refs can differ. New commits can land after the gates, so the workflow can publish code that was not reviewed. Require an explicit release SHA, compute all diffs against it, verify it remains current after the plan gate, and createrelease-v<X.Y.Z>from that SHA.Also applies to: 100-102
🤖 Prompt for AI Agents