From 98ab12df4a46b8f0f8594fe55d349333cc3715e6 Mon Sep 17 00:00:00 2001 From: Chad Bentz <1760475+felickz@users.noreply.github.com> Date: Wed, 15 Jul 2026 00:39:58 -0400 Subject: [PATCH] docs: add Copilot custom instructions for repo maintenance Adds .github/copilot-instructions.md with high-level guidance for future agents working on CodeQL CLI version bumps and pack publishing: judgment calls that need a human, known failure modes to design around, coding agent delegation practices, PR hygiene, and timing expectations. Complements CONTRIBUTING.md's mechanical release process rather than duplicating it. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 84006984-666d-4926-bbb8-795d91f3b5ab --- .github/copilot-instructions.md | 85 +++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..477c8f2a --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,85 @@ +# Copilot instructions for CodeQL-Community-Packs + +This repo periodically bumps its pinned CodeQL CLI version and publishes query/library packs to +GHCR. **`CONTRIBUTING.md`'s "Releases & publishing" section is the authoritative, mechanical +process** — read it first. This file is higher-level guidance for the parts that process doc can't +cover: judgment calls, failure modes, and habits that keep this work from going sideways. + +## Before starting any version-bump work + +- Check for an already-in-flight bump first: open PRs on `chore/update-codeql-cli-*` branches, the + "CodeQL CLI update available" tracking issue, and recent `update-codeql-version.yml` runs. Don't + start a second bump on top of an unfinished one. +- Confirm `.codeqlversion` and `.release.yml`'s `version:` on `main` actually match your assumptions + before triggering anything — don't trust stale context from an earlier session or PR description. + +## Judgment calls — flag to a human, don't resolve solo + +- **Whether/when to take a CLI bump at all.** Detection only flags that a newer CLI exists; taking + the upgrade (and owning whatever it breaks) is a deliberate, human-timed decision, not something + to run unattended just because a newer version is available. +- **Whether a failure is our bug or upstream's.** Before treating a dependency/registry failure as + something to fix in this repo, check whether it's specific to one language or affects the + upstream library broadly (compare against the equivalent upstream package/pin for other + languages at the same CodeQL release tag). Genuine upstream gaps (missing/unpublished packages, + broken releases) need to wait on upstream, not a workaround here — confirm which case you're in + with the user before proceeding either way. +- **Combining a release cut with a dependency-refresh bump** vs. keeping them as separate PRs. + Prefer separate when breakage is plausible (most minor/major CLI bumps); only combine them when + you're confident CI will be green without further fixes. +- **Deciding how to fix upstream API breakage.** Mechanically silencing a warning or deprecation is + not the same as correctly migrating to the replacement API — confirm the replacement's semantics + actually match before treating a fix as done. + +## Known failure modes to design around + +- **Per-language loops with no failure isolation are fragile.** Any automation that iterates over + every language/pack directory and dies on the first hard error will silently discard all + progress made before the failure, with no partial PR or partial commit. When you hit this, don't + just retry — isolate which language/pack is actually broken, and prefer fixing or working around + it (or, if you're touching the automation itself, add per-item error isolation) rather than + re-running the whole thing hoping it clears. +- **A strict "fail on any warning" compile mode hides everything after the first failure.** Always + do a full, non-aborting sweep across every language yourself before trusting a single CI failure + report as the exhaustive list of what's broken — otherwise you'll fix one thing, re-push, and + discover the next issue only on the following CI run. +- **A fully green compile/test stage does not mean CI passed overall.** Separate aggregation/ + validation jobs can still fail on result-level diffs even when every per-language job is + individually green. Always check the overall run conclusion, not just individual job status. +- **Not every CI failure is locally reproducible.** Environment gaps (missing local tooling, + CI-only fixture checkouts) can block a local repro even when the underlying fix is correct. When + this happens, reconstruct the expected change directly and precisely from the CI-reported diff + rather than skipping it or guessing at a fix. +- **Local diagnostic runs can leave incidental changes behind** (e.g. lockfile churn from a + dependency-resolution command run just to investigate). Diff your changes before committing and + strip out anything that isn't part of the actual fix. +- **Never hand-edit a value that an automation tool computes as a delta.** If a release-bump tool + determines its next version by diffing against the current recorded value, editing that value + directly removes the delta it needs and causes it to overshoot on its next run. + +## Delegating to the Copilot coding agent + +- Scope each delegated task to one language (or one clearly-bounded unit of work) at a time rather + than one comprehensive multi-language ask. Coding agent sessions have a real time budget; a + narrower scope finishes with headroom to spare and makes a timeout non-fatal, since whatever's + already committed survives independently. +- Front-load the task with exact file/line/replacement detail when you already know it (e.g. from + your own local investigation) rather than leaving the agent to rediscover failures one CI run at + a time. + +## PR hygiene + +- **Before calling any PR done or merge-ready**, proactively fetch and review automated reviewer + comments — don't wait to be asked. Verify each comment against real evidence (logs, actual + tool/API behavior) rather than assuming it's correct, fix genuine issues, and reply on-thread + explaining the fix or why none was needed. +- **Never leave a review comment thread unanswered or silently resolved.** If you notice one that + was closed without a reply, go back and reply — even after the fact. + +## Timing expectations + +- Full multi-language CI runs and full publish runs are legitimately slow (tens of minutes each, + with the slowest single language/pack job often the long pole). Don't assume a stall just + because a run has been going for a while — check run/job status before intervening. +- Budget generously for coding agent sessions and check status periodically rather than assuming + quick turnaround, especially for anything spanning multiple files or languages.