revize release skills - #836
Conversation
WalkthroughThe PR adds a gated ChangesRelease workflow
Estimated code review effort: 2 (Simple) | ~10 minutes Sequence Diagram(s)sequenceDiagram
participant ReleaseCommand
participant LibraryRepository
participant ContractsWizardRepository
participant DocsRepository
participant GitHub
participant Netlify
ReleaseCommand->>LibraryRepository: run version and audit checks
ReleaseCommand->>ContractsWizardRepository: discover and synchronize Wizard changes
ReleaseCommand->>DocsRepository: assess and prepare documentation updates
ReleaseCommand->>GitHub: create release branch and optional draft release
GitHub->>Netlify: trigger publishing after branch push
Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/commands/release.md:
- Line 52: Update the checklist code fence in the release instructions to
declare the text language, resolving the MD040 unlabeled-fence violation while
preserving the checklist content.
- Line 48: Update the release workflow around the preflight evidence and
publication steps to require an explicit release SHA, use that immutable commit
for all tag comparisons and diff evidence, and revalidate that the SHA is still
the intended current base after the plan gate. Change the release branch
creation in the main publication flow to start from the validated SHA rather
than newly pulled main, preserving the release-v<X.Y.Z> naming.
- Around line 65-71: Enforce a complete version-bump safety gate in both command
flows: in .claude/commands/release.md lines 65-71, require confirmation of the
full README, Cargo.toml, and Cargo.lock edit plan before invoking version-bump;
in .claude/commands/version-bump.md lines 2-13, add a clean-working-tree
preflight and require explicit plan confirmation before applying any changes,
including Cargo.lock updates.
- Around line 118-124: Add the Dev3 repository to the release inputs in the plan
before the compatibility sweep: specify its local checkout path, branch
convention, and fallback URLs alongside the existing repository entries, so the
`languages/soroban/` pointer skills can be located and fetched.
- Around line 107-111: Update the release workflow’s Plan and Apply steps to
define new_ref as the exact commit SHA confirmed in Step 6, then use it in the
contributor commands and pass --target <new_ref> to gh release create. Define
<draft> as the generated notes-file path before referencing it with
--notes-file.
- Around line 82-89: Update the Wizard PR workflow around the relevance check
and merge plan to identify the PR corresponding to the current release by
matching its release version or branch, rather than selecting from the broad
search results. Before offering gh pr merge, verify the matched PR’s files and
CI status, while preserving the requirement for explicit merge confirmation.
In `@CLAUDE.md`:
- Around line 202-205: Update the `/release` summary in CLAUDE.md to include
auditing and updating the release skills as part of its scope, matching
skill-maintenance step 8 in `.claude/commands/release.md` while preserving the
existing checklist description.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 78b3c6ca-0316-4618-aa8e-ff645480d7cf
📒 Files selected for processing (4)
.claude/commands/release.md.claude/commands/version-bump.mdCLAUDE.mdCONTRIBUTING.md
| 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. |
There was a problem hiding this comment.
🗄️ 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 current main and 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 create release-v<X.Y.Z> from that SHA.
Also applies to: 100-102
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/commands/release.md at line 48, Update the release workflow around
the preflight evidence and publication steps to require an explicit release SHA,
use that immutable commit for all tag comparisons and diff evidence, and
revalidate that the SHA is still the intended current base after the plan gate.
Change the release branch creation in the main publication flow to start from
the validated SHA rather than newly pulled main, preserving the release-v<X.Y.Z>
naming.
|
|
||
| ## Checklist (tracking template) | ||
|
|
||
| ``` |
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 text for this checklist block.
🧰 Tools
🪛 markdownlint-cli2 (0.23.2)
[warning] 52-52: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/commands/release.md at line 52, Update the checklist code fence in
the release instructions to declare the text language, resolving the MD040
unlabeled-fence violation while preserving the checklist content.
Source: Linters/SAST tools
| ### 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. |
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 version-bump, while the standalone command permits direct edits without a clean-tree check or full plan confirmation. This can mix uncommitted work with release changes and can modify Cargo.lock without approval.
.claude/commands/release.md#L65-L71: require confirmation for the complete README,Cargo.toml, andCargo.lockplan before delegation..claude/commands/version-bump.md#L2-L13: add the clean-tree preflight and plan/apply gate for standalone execution.
📍 Affects 2 files
.claude/commands/release.md#L65-L71(this comment).claude/commands/version-bump.md#L2-L13
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/commands/release.md around lines 65 - 71, Enforce a complete
version-bump safety gate in both command flows: in .claude/commands/release.md
lines 65-71, require confirmation of the full README, Cargo.toml, and Cargo.lock
edit plan before invoking version-bump; in .claude/commands/version-bump.md
lines 2-13, add a clean-working-tree preflight and require explicit plan
confirmation before applying any changes, including Cargo.lock updates.
| - **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. |
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 gh pr merge.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/commands/release.md around lines 82 - 89, Update the Wizard PR
workflow around the relevance check and merge plan to identify the PR
corresponding to the current release by matching its release version or branch,
rather than selecting from the broad search results. Before offering gh pr
merge, verify the matched PR’s files and CI status, while preserving the
requirement for explicit merge confirmation.
| - **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. |
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:
GitHub CLI gh release create documentation --target default branch tag creation --notes-file
💡 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:
- 1: https://cli.github.com/manual/gh_release_create
- 2: https://manpages.ubuntu.com/manpages/jammy/man1/gh-release-create.1.html
- 3: https://man.archlinux.org/man/extra/github-cli/gh-release-create.1.en
- 4: https://man.archlinux.org/man/gh-release-create.1.en.raw
- 5: https://www.mankier.com/1/gh-release-create
- 6: gh release create question and general feedback cli/cli#2133
Pin the GitHub release to the confirmed release commit.
Define new_ref as the exact commit SHA selected in Step 6. Use it in the contributor commands and pass --target <new_ref> to gh release create; otherwise, a missing tag is created from the default branch. Define <draft> as the generated notes-file path before using --notes-file.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/commands/release.md around lines 107 - 111, Update the release
workflow’s Plan and Apply steps to define new_ref as the exact commit SHA
confirmed in Step 6, then use it in the contributor commands and pass --target
<new_ref> to gh release create. Define <draft> as the generated notes-file path
before referencing it with --notes-file.
| - **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. |
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 languages/soroban/, but the repository table lists only stellar-contracts, contracts-wizard, and docs. The command cannot locate or fetch the Dev3 skills. Add the Dev3 checkout path, branch, and fallback URLs before relying on this compatibility sweep.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/commands/release.md around lines 118 - 124, Add the Dev3 repository
to the release inputs in the plan before the compatibility sweep: specify its
local checkout path, branch convention, and fallback URLs alongside the existing
repository entries, so the `languages/soroban/` pointer skills can be located
and fetched.
| - `/release` — the full release checklist end to end: READMEs, version | ||
| bump, audit report, Wizard PR, docs site, release branch, release | ||
| notes. Confirms with the user before every step. See | ||
| `.claude/commands/release.md`. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Include skill maintenance in the /release scope.
.claude/commands/release.md includes skill-maintenance step 8, but this summary ends at release notes. State that /release also audits and updates the release skills so the documented scope matches the command.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CLAUDE.md` around lines 202 - 205, Update the `/release` summary in CLAUDE.md
to include auditing and updating the release skills as part of its scope,
matching skill-maintenance step 8 in `.claude/commands/release.md` while
preserving the existing checklist description.
1 participant
Revision of skills to be more compatible with Dev3
PR Checklist
Summary by CodeRabbit
New Features
Documentation