|
| 1 | +--- |
| 2 | +applyTo: "**" |
| 3 | +excludeAgent: "code-review" |
| 4 | +--- |
| 5 | + |
| 6 | +# Release — instructions for Copilot coding agent |
| 7 | + |
| 8 | +Follow these steps when cutting a new release of `github-code-search`. |
| 9 | + |
| 10 | +## 1. Determine the version bump |
| 11 | + |
| 12 | +This project follows [Semantic Versioning](https://semver.org/): |
| 13 | + |
| 14 | +| Change type | Bump | Example | |
| 15 | +| ------------------------------------------ | ------- | -------------- | |
| 16 | +| Bug fix only (no new behaviour, no API change) | `patch` | 1.2.4 → 1.2.5 | |
| 17 | +| New feature, backward-compatible | `minor` | 1.2.4 → 1.3.0 | |
| 18 | +| Breaking change (CLI flag removed/renamed) | `major` | 1.2.4 → 2.0.0 | |
| 19 | + |
| 20 | +## 2. Bump the version |
| 21 | + |
| 22 | +```bash |
| 23 | +bun pm version patch # or minor / major |
| 24 | +``` |
| 25 | + |
| 26 | +If the working tree is dirty (staged or unstaged changes), `bun pm version` will refuse. In that case bump directly in `package.json`, then commit the version bump as the first commit on the release branch. |
| 27 | + |
| 28 | +## 3. Write the blog post |
| 29 | + |
| 30 | +**Required for minor and major releases. Optional (but encouraged) for patch releases.** |
| 31 | + |
| 32 | +1. Create `docs/blog/release-v<X-Y-Z>.md` — use existing posts as format reference: |
| 33 | + - `docs/blog/release-v1-3-0.md` (minor, feature-focused) |
| 34 | + - `docs/blog/release-v1-4-0.md` (minor, TUI/community-focused) |
| 35 | + - Front-matter: `title`, `description`, `date` (ISO 8601). |
| 36 | + - Structure: `## Highlights` → one `###` section per major change group → `## Upgrade` at the bottom. |
| 37 | + - The upgrade section must include the `github-code-search upgrade` command and a link to the GitHub Releases page. |
| 38 | + |
| 39 | +2. Update `docs/blog/index.md` — prepend a row to the `## v1 series` table: |
| 40 | + ```markdown |
| 41 | + | [vX.Y.Z](./release-vX-Y-Z) | One-line summary of highlights | |
| 42 | + ``` |
| 43 | + |
| 44 | +3. Update `CHANGELOG.md` — update (or add) the matching row in the table: |
| 45 | + ```markdown |
| 46 | + | [vX.Y.Z](https://fulll.github.io/github-code-search/blog/release-vX-Y-Z) | One-line summary | |
| 47 | + ``` |
| 48 | + Never leave a row with `_pending_` in `CHANGELOG.md` when cutting the release. |
| 49 | + |
| 50 | +## 4. Create the release branch and commit |
| 51 | + |
| 52 | +```bash |
| 53 | +VERSION=$(jq -r .version package.json) |
| 54 | +git checkout -b release/$VERSION |
| 55 | +git add package.json docs/blog/release-v*.md docs/blog/index.md CHANGELOG.md |
| 56 | +git commit -S -m "v$VERSION" |
| 57 | +``` |
| 58 | + |
| 59 | +> **All commits must be signed** — use `git commit -S` or `git config --global commit.gpgsign true`. |
| 60 | +
|
| 61 | +## 5. Tag and push |
| 62 | + |
| 63 | +```bash |
| 64 | +VERSION=$(jq -r .version package.json) |
| 65 | +git tag v$VERSION |
| 66 | +git push origin release/$VERSION --tags |
| 67 | +``` |
| 68 | + |
| 69 | +The tag push triggers **`cd.yaml`**: |
| 70 | +1. Builds self-contained binaries for all six targets. |
| 71 | +2. Creates a GitHub Release with all binaries attached. |
| 72 | +3. For major tags (`vX.0.0`): triggers `docs.yml` → docs snapshot + `versions.json` update. |
| 73 | + |
| 74 | +Do **not** create the GitHub Release manually — the CD pipeline handles it. |
| 75 | + |
| 76 | +## 6. Required validation before tagging |
| 77 | + |
| 78 | +```bash |
| 79 | +bun test # full suite green |
| 80 | +bun run lint # oxlint — zero errors |
| 81 | +bun run format:check # oxfmt — no diff |
| 82 | +bun run knip # no unused exports |
| 83 | +bun run build.ts # binary compiles |
| 84 | +``` |
| 85 | + |
| 86 | +## 7. Post-release checklist |
| 87 | + |
| 88 | +- [ ] GitHub Release created automatically by CD pipeline (verify within ~5 min after tag push) |
| 89 | +- [ ] Blog post live at `https://fulll.github.io/github-code-search/blog/release-vX-Y-Z` |
| 90 | +- [ ] `bun run docs:build` succeeds locally (spot-check the new blog entry) |
| 91 | +- [ ] `CHANGELOG.md` has no `_pending_` entries |
| 92 | +- [ ] For **major** releases: versioned docs snapshot available at `/github-code-search/vX/` |
| 93 | + |
| 94 | +## 8. Module map — what to document per release type |
| 95 | + |
| 96 | +| Changed area | Cover in the blog post | |
| 97 | +| -------------------------- | -------------------------------------------------------------------- | |
| 98 | +| `src/tui.ts` | UX / interaction changes (keyboard shortcuts, new modes) | |
| 99 | +| `src/render/` | Visual changes (colours, layout, new components) | |
| 100 | +| `src/aggregate.ts` | New filter or exclusion options | |
| 101 | +| `src/group.ts` | Team-grouping behaviour changes | |
| 102 | +| `src/output.ts` | New output formats or structural changes to existing ones | |
| 103 | +| `src/api.ts` | New GitHub API features, pagination changes, scope requirements | |
| 104 | +| `src/upgrade.ts` | Upgrade command improvements | |
| 105 | +| `github-code-search.ts` | New CLI flags, subcommands, breaking option renames | |
| 106 | +| Community / project files | SECURITY, CODE_OF_CONDUCT, CONTRIBUTING changes worth surfacing | |
0 commit comments