From e115121b83d146638b06511e4caac21e5c0d7a5b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20HOUZ=C3=89?= Date: Mon, 9 Mar 2026 02:27:37 +0100 Subject: [PATCH] v1.8.2 Patch release for #102: rate-limit errors aborting multi-page searches. Also: - Add docs/blog/release-v1-8-2.md and update docs/blog/index.md - Replace \`bun pm version\` with direct package.json editing across all release instructions, skills and AGENTS.md (\`bun pm version\` auto-creates a git commit and tag, which conflicts with the release workflow) - Add explicit "ask the user interactively" requirement before writing any release blog post in AGENTS.md, release.instructions.md, skills/release.md, bug-fixing.instructions.md and implement-feature.instructions.md --- .../instructions/bug-fixing.instructions.md | 4 +- .../implement-feature.instructions.md | 8 +- .github/instructions/release.instructions.md | 27 ++++++- .github/skills/release.md | 38 ++++++++++ AGENTS.md | 18 ++++- CHANGELOG.md | 1 + docs/blog/index.md | 1 + docs/blog/release-v1-8-2.md | 73 +++++++++++++++++++ package.json | 2 +- 9 files changed, 159 insertions(+), 13 deletions(-) create mode 100644 docs/blog/release-v1-8-2.md diff --git a/.github/instructions/bug-fixing.instructions.md b/.github/instructions/bug-fixing.instructions.md index 49d6961..97be174 100644 --- a/.github/instructions/bug-fixing.instructions.md +++ b/.github/instructions/bug-fixing.instructions.md @@ -92,7 +92,7 @@ Add a one-line comment above the fix if the root cause is non-obvious: Once the PR is merged into `main`, publish a **patch** release: ```bash -bun pm version patch # bumps package.json: 1.2.4 → 1.2.5 +sed -i '' 's/"version": ".*"/"version": "X.Y.Z"/' package.json # bump directly — do NOT use bun pm version git checkout -b release/$(jq -r .version package.json) git add package.json git commit -S -m "v$(jq -r .version package.json)" @@ -101,4 +101,6 @@ git push origin release/$(jq -r .version package.json) --tags ``` The tag push triggers `cd.yaml` which builds all-platform binaries and creates the GitHub Release automatically. + +For the blog post (optional for patch, but encouraged): **ask the user interactively** for the highlights and description before writing `docs/blog/release-v.md`. See the full release guide in `AGENTS.md § Release process`. diff --git a/.github/instructions/implement-feature.instructions.md b/.github/instructions/implement-feature.instructions.md index 5dbdb82..e99daf7 100644 --- a/.github/instructions/implement-feature.instructions.md +++ b/.github/instructions/implement-feature.instructions.md @@ -77,10 +77,8 @@ bun run build.ts # binary compiles without errors Once the PR is merged into `main`, publish a **minor** (new feature) or **major** (breaking change) release: ```bash -bun pm version minor # new feature: 1.2.4 → 1.3.0 -# or -bun pm version major # breaking change: 1.2.4 → 2.0.0 - +sed -i '' 's/"version": ".*"/"version": "X.Y.Z"/' package.json # bump directly — do NOT use bun pm version +# X.Y.Z: new feature → 1.2.4 → 1.3.0 | breaking change → 1.2.4 → 2.0.0 git checkout -b release/$(jq -r .version package.json) git add package.json git commit -S -m "v$(jq -r .version package.json)" @@ -90,7 +88,7 @@ git push origin release/$(jq -r .version package.json) --tags The tag push triggers `cd.yaml` which builds all-platform binaries and creates the GitHub Release automatically. -For **minor and major releases**, also write the blog post **before pushing the tag**: +For **minor and major releases**, a blog post is **required** — **ask the user interactively** for the highlights and description before writing `docs/blog/release-v.md`. Do not draft it from code alone. - Create `docs/blog/release-v.md` with feature highlights - Add a row in `docs/blog/index.md` diff --git a/.github/instructions/release.instructions.md b/.github/instructions/release.instructions.md index 3e24ba9..15c1760 100644 --- a/.github/instructions/release.instructions.md +++ b/.github/instructions/release.instructions.md @@ -21,16 +21,39 @@ This project follows [Semantic Versioning](https://semver.org/): ## 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. + ```bash -bun pm version patch # or minor / major +# 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 ``` -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. +Verify the bump before committing: + +```bash +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.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) diff --git a/.github/skills/release.md b/.github/skills/release.md index c581d0a..7e8c270 100644 --- a/.github/skills/release.md +++ b/.github/skills/release.md @@ -5,6 +5,34 @@ This skill complements `.github/instructions/release.instructions.md`. --- +## Version bump — important note + +**Never use `bun pm version patch/minor/major` to bump the version.** + +Unlike `npm version`, Bun's implementation creates both a git commit _and_ a git +tag in a single operation. This is incompatible with the release workflow: + +- The tag must land on the dedicated `release/X.Y.Z` branch, not on `main`. +- The blog post and `CHANGELOG.md` must be committed _before_ the version tag is + pushed (the CD pipeline reads the tag to build binaries and name the release). +- Undoing an unwanted auto-tag requires `git tag -d vX.Y.Z` locally and + `git push origin --delete vX.Y.Z` on the remote — easy to forget one of the + two, which can trigger the CD pipeline prematurely. + +**Correct approach:** + +```bash +# Bump directly in package.json +sed -i '' 's/"version": ".*"/"version": "X.Y.Z"/' package.json + +# Verify +jq -r .version package.json +``` + +The git commit and tag are created separately in steps 4 and 5. + +--- + ## Semver decision guide | Change type | Bump | Example | @@ -57,6 +85,16 @@ Pushing `vX.Y.Z` triggers the release pipeline automatically: Required for **minor** and **major** releases. Optional for patch (GitHub Release body is sufficient for patch). +> **Always ask the user interactively before writing the blog post.** +> Do not invent highlights, descriptions or examples from code alone. +> Ask at minimum: +> +> - Which changes deserve a `###` section and why? +> - Suggested one-line `description` for the front-matter. +> - Any before/after CLI output or screenshots to illustrate? +> +> Then draft the post and show it to the user for approval before committing. + **Front-matter:** ```yaml diff --git a/AGENTS.md b/AGENTS.md index bd515a6..28f5887 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -177,10 +177,11 @@ This project follows [Semantic Versioning](https://semver.org/): ### Step-by-step ```bash -# 1. Bump the version in package.json (pick one) -bun pm version patch # bug fix -bun pm version minor # new feature -bun pm version major # breaking change +# 1. Bump the version in package.json directly +# Do NOT use `bun pm version` — it creates a git commit AND a git tag +# automatically, which conflicts with the release workflow below. +sed -i '' 's/"version": ".*"/"version": "X.Y.Z"/' package.json +jq -r .version package.json # verify # 2. Create the release branch and commit git checkout -b release/$(jq -r .version package.json) @@ -215,6 +216,15 @@ Pushing a **major** tag (`vX.0.0`) additionally triggers **`docs.yml` → snapsh ### Blog post requirement +> **Always ask the user interactively before writing the blog post.** +> Do not invent highlights or descriptions from code alone. Ask at minimum: +> +> - Which changes should be highlighted? +> - Is there a one-line description for the front-matter? +> - Any before/after CLI output examples to include? +> +> Only proceed to write `docs/blog/release-v.md` once you have the user's input. + | Release type | Blog post | Location | | ------------ | ----------------------------------------------------------- | --------------------------------- | | **Major** | Required (written by hand — CI stub automates the skeleton) | `docs/blog/release-vX-0-0.md` | diff --git a/CHANGELOG.md b/CHANGELOG.md index 9bb4411..d88abdf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ Each release entry covers the motivation, new features, breaking changes (if any | Version | Blog post | | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | +| [v1.8.2](https://fulll.github.io/github-code-search/blog/release-v1-8-2) | Fix rate-limit errors aborting multi-page searches; auto-wait and retry with live progress | | [v1.8.1](https://fulll.github.io/github-code-search/blog/release-v1-8-1) | Fix silent hang after pagination bar — concurrency cap + progress bar for line-number resolution | | [v1.8.0](https://fulll.github.io/github-code-search/blog/release-v1-8-0) | Purple TUI theme, fetch progress bar, position indicator, line-anchored file links, Esc to close help | | [v1.7.0](https://fulll.github.io/github-code-search/blog/release-v1-7-0) | Shell completions (bash/zsh/fish) + extended syntax highlighting (PHP, C/C++, Swift, Terraform/HCL, Dockerfile) | diff --git a/docs/blog/index.md b/docs/blog/index.md index a0f63c6..fa1b964 100644 --- a/docs/blog/index.md +++ b/docs/blog/index.md @@ -11,6 +11,7 @@ Full release notes and changelogs are always available on | Release | Highlights | | -------------------------- | ---------------------------------------------------------------------------------------------------------- | +| [v1.8.2](./release-v1-8-2) | Fix rate-limit errors aborting multi-page searches — auto-wait and resume with live feedback | | [v1.8.1](./release-v1-8-1) | Fix silent hang after pagination bar — concurrency cap + progress bar for line-number resolution | | [v1.8.0](./release-v1-8-0) | Purple TUI theme, fetch progress bar, position indicator, line-anchored file links, Esc to close help | | [v1.7.0](./release-v1-7-0) | Shell completions (bash/zsh/fish), extended syntax highlighting (PHP, C/C++, Swift, Terraform, Dockerfile) | diff --git a/docs/blog/release-v1-8-2.md b/docs/blog/release-v1-8-2.md new file mode 100644 index 0000000..687d58b --- /dev/null +++ b/docs/blog/release-v1-8-2.md @@ -0,0 +1,73 @@ +--- +title: "What's new in v1.8.2" +description: "Bug fix: multi-page searches no longer abort when GitHub rate-limits mid-pagination — the CLI now waits and resumes automatically." +date: 2026-03-09 +--- + +# What's new in github-code-search v1.8.2 + +> Full release notes: + +## Highlights + +### Fix: multi-page searches aborted by rate limits now auto-resume + +When searching across a large organisation with many results (close to the +GitHub 1 000-result cap), the CLI could crash mid-way through pagination with: + +``` + Fetching results from GitHub… ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░ page 9/10 +error: GitHub API rate limit exceeded. Please retry in 53 seconds. +``` + +The search was lost at ~90 % completion and had to be restarted from scratch. + +#### Root causes (three compounding issues) + +**1. Long rate-limit waits threw immediately.** +When `x-ratelimit-reset` indicated a wait longer than 10 seconds, +`fetchWithRetry` threw an error instead of waiting. The pagination loop +propagated this exception and discarded all pages already fetched. + +**2. Secondary rate limits were not recognised.** +GitHub secondary rate limits return `403 + Retry-After` (without +`x-ratelimit-remaining: 0`). This pattern bypassed the retry logic entirely +and surfaced as an unhandled API error. + +**3. 422 error when results hit exactly 1 000.** +When `total_count` was an exact multiple of 100 (e.g. 1 000 results across 10 +full pages), the pagination loop attempted a page 11. GitHub rejects this with +`422 Cannot access beyond the first 1000 results`. + +#### What changed + +- **Auto-wait with visible feedback.** When a rate-limit response is received + during pagination, the CLI now prints a message, waits for the exact duration + indicated by GitHub (`x-ratelimit-reset` or `Retry-After` + 1 s clock-skew + buffer), and resumes automatically — no retry counting, no data lost: + + ``` + Fetching results from GitHub… ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░ page 9/10 + Rate limited — waiting 53 seconds, resuming automatically… + Fetching results from GitHub… ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ page 10/10 + ``` + +- **Secondary rate limit detection.** Any `403 + Retry-After` response is now + treated as a retriable rate-limit condition. + +- **Page 11 guard.** `fetchAllResults` now short-circuits before requesting + a page beyond `totalPages`, preventing the 422 error at the cap. + +**Before:** error at page 9, search lost. +**After:** transparent pause, TUI opens with all 1 000 results. + +--- + +## Upgrade + +```bash +github-code-search upgrade +``` + +Or download the latest binary directly from the +[GitHub Releases page](https://github.com/fulll/github-code-search/releases/tag/v1.8.2). diff --git a/package.json b/package.json index 87e07af..a500b8a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "github-code-search", - "version": "1.8.1", + "version": "1.8.2", "description": "Interactive GitHub code search with per-repo aggregation", "keywords": [ "bun",