From f24aa888b59c3878fa146d1628694b9c2e234ff8 Mon Sep 17 00:00:00 2001 From: 0xrsydn Date: Mon, 13 Apr 2026 14:39:40 +0700 Subject: [PATCH] docs: add idx release skill --- .codex/skills/idx-release/SKILL.md | 137 +++++++++++++++++++ .codex/skills/idx-release/agents/openai.yaml | 4 + 2 files changed, 141 insertions(+) create mode 100644 .codex/skills/idx-release/SKILL.md create mode 100644 .codex/skills/idx-release/agents/openai.yaml diff --git a/.codex/skills/idx-release/SKILL.md b/.codex/skills/idx-release/SKILL.md new file mode 100644 index 0000000..b26feff --- /dev/null +++ b/.codex/skills/idx-release/SKILL.md @@ -0,0 +1,137 @@ +--- +name: idx-release +description: Prepare, publish, and repair versioned idx-cli application releases across Cargo.toml, Git tags, GitHub Releases, and crates.io. Use when Codex needs to cut a new app release, backfill a missing GitHub release, reconcile mismatched tags and crates.io versions, or verify release hygiene. Do not use this skill for the monthly ownership snapshot artifact flow under ownership-snapshot-current. +--- + +# IDX Release + +## Overview + +Handle versioned `idx-cli` application releases. Keep the package version, release +commit, Git tag, GitHub Release, and crates.io publication aligned. Treat the +ownership snapshot artifacts as a separate release track. + +## Read First + +Read these files before mutating release state: + +- `Cargo.toml` for the package version +- `TODO.md` for the latest smoke findings and release-readiness notes +- `README.md` if install or publish notes may need updates +- `docs/OWNERSHIP_SYNC.md` and `docs/OWNERSHIP_PUBLISH.md` only when checking + ownership-sync behavior or keeping snapshot and app releases separated + +## Keep Release Tracks Separate + +Treat these as different things: + +- Versioned app releases: `v0.1.0`, `v0.2.1`, `v0.2.2` +- Snapshot artifact release: `ownership-snapshot-current` + +Do not compare `ownership-snapshot-current` against crates.io, and do not let it +drive app-release hygiene decisions. Avoid `.../releases/latest/download/...` for +ownership snapshot docs or manifests because GitHub's latest app release can move. + +## Determine The Source Commit First + +Start by identifying the exact commit that corresponds to the target version. + +- If crates.io already has the version, find the historical commit where + `Cargo.toml` was bumped or published. +- If the Git tag already exists, do not move it. +- If the GitHub Release object is missing but the tag exists, backfill the + release object only. +- If crates.io has a version that GitHub does not, create the missing tag and + release at the historical commit, not at current `HEAD`. + +Use commands like: + +```bash +rg '^version\\s*=\\s*"' Cargo.toml +git log --oneline --decorate -- Cargo.toml +git blame -L 1,20 Cargo.toml +gh release list --repo 0xrsydn/idx-cli --limit 20 +gh api 'repos/0xrsydn/idx-cli/tags?per_page=20' +curl -fsSL https://crates.io/api/v1/crates/idx-cli +``` + +## Verify Before Publishing + +For a real release or release-hygiene fix, verify the repo state first. + +Run the standard checks inside `nix develop`: + +```bash +nix develop --command cargo build +nix develop --command cargo clippy -- -D warnings +nix develop --command cargo test +nix develop --command cargo package --locked +``` + +Run targeted smoke when the release changes user-facing CLI behavior. For +ownership-sync changes, re-verify a clean-machine flow: + +```bash +env XDG_DATA_HOME=/tmp/idx-release-check/data \ + XDG_CACHE_HOME=/tmp/idx-release-check/cache \ + XDG_CONFIG_HOME=/tmp/idx-release-check/config \ + ./target/debug/idx ownership sync +``` + +If the user only asks for inspection or planning, stop after verification. + +## Publish Or Repair GitHub Release State + +Use `gh` for remote release hygiene. + +For backfilled historical releases: + +- use `gh release create --verify-tag --latest=false ...` when the tag + already exists and only the release object is missing +- use `gh release create --target --latest=false ...` when both the + tag and release are missing for an older version + +For the current stable app release: + +- use `gh release create --target --latest ...` when that version + should become the latest GitHub app release + +After creating or repairing a release, verify: + +```bash +gh api repos/0xrsydn/idx-cli/releases/latest +gh release list --repo 0xrsydn/idx-cli --limit 20 +gh api 'repos/0xrsydn/idx-cli/tags?per_page=20' +``` + +## Publish To crates.io Carefully + +Treat `cargo publish` as irreversible. + +- Do not publish to crates.io unless the user clearly asked to ship a new + version. +- Do not publish a version that already exists on crates.io. +- Do not publish from a dirty tree unless the user explicitly accepts that risk. + +Before publish, verify the version in `Cargo.toml`, confirm the intended commit, +and make sure the GitHub tag/release plan matches that exact version. + +## Write Release Notes With Scope Discipline + +Keep notes aligned to the actual tagged commit. + +- Do not describe features that landed after the tagged commit. +- If backfilling a release object, say that clearly in the notes. +- If a release only fixes parser/import behavior, do not present later snapshot + automation work as part of that version. +- Mention ownership-sync behavior only if that version actually included it. + +## Final Verification + +Before concluding, report: + +- the version on crates.io +- the Git tag and commit SHA +- the GitHub Release URL +- whether GitHub `latest` now points at the expected app release +- whether any snapshot-artifact release state remains intentionally separate diff --git a/.codex/skills/idx-release/agents/openai.yaml b/.codex/skills/idx-release/agents/openai.yaml new file mode 100644 index 0000000..8e083c1 --- /dev/null +++ b/.codex/skills/idx-release/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "IDX Release" + short_description: "Publish and repair idx-cli app releases" + default_prompt: "Use $idx-release to prepare, publish, or repair an idx-cli versioned app release."