Instruction file imported from fulll/github-code-search (.github/instructions/release.instructions.md). Copyright stays with the author.

Release — instructions for Copilot coding agent

Skill reference: for the semver decision guide, CD pipeline mechanics, binary targets, blog post format reference and versioned docs snapshot details read .github/skills/release.md first.

Follow these steps when cutting a new release of github-code-search.

1. Determine the version bump

This project follows Semantic Versioning:

2. Bump the version

Edit package.json directly — do not use bun pm version.

bun pm version automatically creates a git commit and a git tag in one shot, which conflicts with the release workflow (tag must land on the release branch, not on the current branch, and only after the blog post / CHANGELOG are ready). Undoing that auto-tag with git tag -d and git push --delete is error-prone.

# Option A — in-place sed (reliable, no interactive editor needed)
sed -i '' 's/"version": ".*"/"version": "X.Y.Z"/' package.json

# Option B — edit package.json manually, change the "version" field

Verify the bump before committing:

jq -r .version package.json   # should print X.Y.Z

3. Write the blog post

Required for minor and major releases. Optional (but encouraged) for patch releases.

Ask the user interactively before writing. Do not invent highlights or descriptions. Before drafting the post, ask the user:

• Which changes should be highlighted?
• Is there a one-line description for the front-matter?
• Any before/after examples or screenshots to include?

Only proceed to write the file once you have the user's input.

1. Create docs/blog/release-v<X-Y-Z>.md — use existing posts as format reference:

   • docs/blog/release-v1-3-0.md (minor, feature-focused)
   • docs/blog/release-v1-4-0.md (minor, TUI/community-focused)
   • Front-matter: title, description, date (ISO 8601).
   • Structure: ## Highlights → one ### section per major change group → ## Upgrade at the bottom.
   • The upgrade section must include the github-code-search upgrade command and a link to the GitHub Releases page.

2. Update docs/blog/index.md — prepend a row to the ## v1 series table:

   | [vX.Y.Z](./release-vX-Y-Z) | One-line summary of highlights |

3. Update CHANGELOG.md — update (or add) the matching row in the table:

   | [vX.Y.Z](https://fulll.github.io/github-code-search/blog/release-vX-Y-Z) | One-line summary |

   Never leave a row with _pending_ in CHANGELOG.md when cutting the release.

4. Create the release branch and commit

VERSION=$(jq -r .version package.json)
git checkout -b release/$VERSION
git add package.json docs/blog/release-v*.md docs/blog/index.md CHANGELOG.md
git commit -S -m "v$VERSION"

All commits must be signed — use git commit -S or git config --global commit.gpgsign true.

5. Tag and push

VERSION=$(jq -r .version package.json)
git tag v$VERSION
git push origin release/$VERSION --tags

The tag push triggers cd.yaml:

1. Builds self-contained binaries for all six targets.
2. Creates a GitHub Release with all binaries attached.
3. For major tags (vX.0.0): triggers docs.yml → docs snapshot + versions.json update.

Do not create the GitHub Release manually — the CD pipeline handles it.

6. Required validation before tagging

bun test               # full suite green
bun run lint           # oxlint — zero errors
bun run format:check   # oxfmt — no diff
bun run knip           # no unused exports
bun run build.ts       # binary compiles

7. Post-release checklist

• GitHub Release created automatically by CD pipeline (verify within ~5 min after tag push)
• Blog post live at https://fulll.github.io/github-code-search/blog/release-vX-Y-Z
• bun run docs:build succeeds locally (spot-check the new blog entry)
  • The version badge in the hero (VersionBadge.vue) reads version from package.json at build time via vite.define — no manual update needed. It auto-points to the new blog post slug (release-vX-Y-Z) derived from the version. Verify it shows the new version after deploy.
• CHANGELOG.md has no _pending_ entries
• For major releases: versioned docs snapshot available at /github-code-search/vX/

8. Module map — what to document per release type