Skip to content

bug-fixing.instructions.md

Latest commit

 

History

History
104 lines (76 loc) · 4.73 KB

bug-fixing.instructions.md

File metadata and controls

104 lines (76 loc) · 4.73 KB
applyTo **
excludeAgent code-review

Bug fixing — instructions for Copilot coding agent

Skill reference: for the extended symptom → module diagnostic table, test-first patterns and minimal fix principles read .github/skills/bug-fixing.md first.

Follow these steps when fixing a bug in this repository.

1. Reproduce the bug before writing any fix

A bug report should include:

  • The exact command that was run (with GITHUB_TOKEN redacted).
  • The observed vs. expected behaviour.
  • The github-code-search --version output (contains commit SHA, OS, architecture).

If the report is incomplete, do not guess. Review the relevant module(s) to locate the most likely root cause.

2. Locate the root cause

Use the module map in AGENTS.md to identify where the bug likely lives:

Symptom Look in
Wrong grouping / filtering of results src/aggregate.ts, src/group.ts
Incorrect markdown / JSON output src/output.ts
Wrong syntax highlighting src/render/highlight.ts
Bad row navigation or visibility src/render/rows.ts
Incorrect select-all / select-none src/render/selection.ts
Wrong stats / summary line src/render/summary.ts
Filter stats incorrect src/render/filter.ts
API pagination or rate-limit issue src/api.ts
TUI keyboard handling / display glitch src/tui.ts
Upgrade failure src/upgrade.ts
CLI option parsing / defaults github-code-search.ts
Completion script wrong / not refreshed on upgrade src/completions.ts, src/upgrade.ts
Completion file written to wrong path src/completions.ts

3. Write a failing test before fixing

For any bug in a pure-function module (aggregate.ts, group.ts, output.ts, render/):

  1. Open (or create) the companion *.test.ts file.
  2. Write a test case that reproduces the exact bug scenario and fails with the current code.
  3. Commit the failing test first (or keep it as part of the same commit with the fix, clearly noted).

This ensures the fix is verified and the regression cannot reappear undetected.

For bugs in tui.ts or api.ts (side-effectful code), a test may not be practical — document the manual reproduction steps in the PR instead.

4. Apply the minimal fix

  • Fix only the root cause. Do not refactor unrelated code in the same PR.
  • Respect the layering: pure functions stay pure, I/O stays in api.ts / tui.ts / entry point.
  • If fixing the bug requires a type change in src/types.ts, update all usages across the codebase.

5. Verify the fix

bun test               # the previously failing test now passes; full suite still green
bun run lint           # oxlint — zero errors
bun run format:check   # oxfmt — no formatting diff
bun run knip           # no unused exports or imports
bun run build.ts       # binary compiles without errors

6. Regression note

Add a one-line comment above the fix if the root cause is non-obvious:

// Fix: <what was wrong and why> — see issue #<N>

7. Commit & pull request

  • Branch name: fix/<short-description> (e.g. fix/exclude-repos-with-org-prefix).
  • Commit message: imperative mood, e.g. Fix --exclude-repositories ignoring org-prefixed names.
  • All commits must be signed (GPG or SSH). Configure once with git config --global commit.gpgsign true. Commits pushed via the GitHub API (Copilot Coding Agent, MCP tools) are automatically Verified by GitHub.
  • PR description:
    • Root cause explanation.
    • Steps to reproduce (before the fix).
    • Steps to verify (after the fix).
    • Reference to the issue number.

8. Release after merge

Once the PR is merged into main, publish a patch release:

bun pm version patch          # bumps package.json: 1.2.4 → 1.2.5
git checkout -b release/$(jq -r .version package.json)
git add package.json
git commit -S -m "v$(jq -r .version package.json)"
git tag v$(jq -r .version package.json)
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. See the full release guide in AGENTS.md § Release process.