You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 0ab6ced
Browse filesBrowse the repository at this point in the historyBrowse files
docs: retire hand-maintained CodeQL version table, point to GitHub Releases (#178)
The "Supported CodeQL versions" table in CONTRIBUTING.md was hand-maintained
and went stale across the last two CLI bumps in a row (PR #173 and #177 both
skipped the "update the table" checklist item). Meanwhile publish.yml's
summary job already generates an equivalent, strictly better table on every
release: it's per-src/lib, links every cell to the exact upstream and
downstream source, and flags drift with a checkmark/mismatch column - so it
can never go stale the way a hand-typed table can.
- CONTRIBUTING.md: replace the stale table with a pointer to the latest
GitHub Release (and .codeqlversion directly for just the CLI version).
Keep the heading (README.md links to its anchor), the pinning-rationale
WARNING box, and the cpp/csharp upstream-queries-pack explanation - none
of that is version-specific or stale.
- update-codeql-version.yml: drop the now-obsolete "Update the Supported
CodeQL versions table in CONTRIBUTING.md" checklist bullet from both
generated PR-body branches (with/without release_bump).
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+36-22Lines changed: 36 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -62,7 +62,7 @@ After the query is merged, we welcome pull requests to improve it.
62
62
63
63
## Supported CodeQL versions
64
64
65
-
Every query pack in this repository is compiled and tested against a specificversion of the upstream CodeQL standard libraries (e.g. `codeql/java-all`). These queries are **only guaranteed to compile** against the exact library versions shown below: newer or older CodeQL CLI/library versions may rename or remove APIs the queries depend on (see [#151](https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/pull/151) for an example, and [#145](https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/issues/145) for the ongoing effort to refresh these pins).
65
+
Every query pack in this repository is compiled and tested against a specific, pinned version of the upstream CodeQL standard libraries (e.g. `codeql/java-all`). These queries are **only guaranteed to compile** against those exact library versions (see the latest release for the current versions): newer or older CodeQL CLI/library versions may rename or remove APIs the queries depend on (see [#151](https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/pull/151) for an example, and [#145](https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/issues/145) for the ongoing effort to refresh these pins).
66
66
67
67
The pinning is codified per language across:
68
68
-[`.codeqlversion`][codeqlversion] (repo root): the CodeQL **CLI** version CI installs and compiles/tests against.
@@ -78,9 +78,9 @@ The pinning is codified per language across:
78
78
`codeql pack upgrade` is run against one directory but not the other, or one `qlpack.yml` pin is
79
79
hand-edited without the other) for them to drift apart. Always upgrade both when bumping
80
80
`.codeqlversion` (the [automated workflow](#updating-the-pinned-codeql-clilibrary-version) does this
81
-
for every pack directory in one pass); the table below only shows `src` for brevity, but the
82
-
auto-generated table in every publish summary (see [Cutting a release](#cutting-a-release)) checks
83
-
both and will flag drift between them.
81
+
for every pack directory in one pass); the auto-generated table in every publish summary (see
82
+
[Cutting a release](#cutting-a-release)) checks both `src` and `lib` independently and will flag
83
+
drift between them.
84
84
85
85
> [!WARNING]
86
86
> **Why `codeql/*` dependencies are pinned to an exact version instead of left as `'*'`:** they used
@@ -119,22 +119,36 @@ The pinning is codified per language across:
119
119
> `codeql/<pkg>: '*'`, that just means its dependencies haven't been re-resolved since, not that the
Most of our query packs only depend on the standard library (`*-all`) for CodeQL's core language APIs. C/C++ and C# are the exception: their `qlpack.yml` also declares a dependency on the upstream `codeql/<language>-queries` pack, because one query (`audit/explore/Dependencies.ql`) reuses a `Metrics.Dependencies` helper that ships with the upstream query pack rather than the standard library. That's an extra surface area those two languages need to stay compatible with.
135
-
136
-
> [!NOTE]
137
-
> This table is maintained by hand today; update it whenever `.codeqlversion` or the `codeql-pack.lock.yml` files are refreshed. For a broader mapping of CodeQL CLI/bundle versions to per-language library versions (useful when triaging why a query compiles locally but not in CI, or vice versa), see the community [CodeQL Bundle Version Tracker](https://github.com/advanced-security/advanced-security-material/blob/main/codeql/codeql-version-tracker.md).
122
+
**This section no longer hand-maintains a version table** - it used to, but that table went stale
123
+
across multiple CLI bumps in a row (nobody remembered to update it, and there was no CI check
124
+
enforcing it) while the *real* answer was already being generated automatically and posted
125
+
somewhere more visible. Don't add one back here; see below for where to actually look.
126
+
127
+
To find the CodeQL CLI/library versions this repo currently builds and tests against:
128
+
129
+
-**[Latest GitHub Release][latest-release]** - every release's notes include an auto-generated
130
+
**"CodeQL standard library & query pack versions"** table (produced by `publish.yml`'s `summary`
131
+
job, see [Cutting a release](#cutting-a-release)), comparing every language's locked `codeql/*`
132
+
dependency - independently for both `src` and `lib`, since they're separately-resolved lock files
133
+
that can drift apart - against what [github/codeql][codeql-repo] itself ships for that exact CLI
134
+
version, with a ✅/mismatch status per row and a direct link to the exact file/line on both sides
135
+
(our lock file, upstream's `qlpack.yml`) so any claim can be verified with one click. This is
136
+
always in sync with what's actually on `main` at release time, because it's generated from the
137
+
real lock files, not typed by hand.
138
+
-**[`.codeqlversion`][codeqlversion]** (repo root) directly, if you just need the pinned CLI
139
+
version and don't need the per-language library breakdown.
140
+
141
+
For a broader mapping of CodeQL CLI/bundle versions to per-language library versions (useful when
142
+
triaging why a query compiles locally but not in CI, or vice versa), see the community
143
+
[CodeQL Bundle Version Tracker](https://github.com/advanced-security/advanced-security-material/blob/main/codeql/codeql-version-tracker.md).
144
+
145
+
Most of our query packs only depend on the standard library (`*-all`) for CodeQL's core language
146
+
APIs. C/C++ and C# are the exception: their `qlpack.yml` also declares a dependency on the upstream
147
+
`codeql/<language>-queries` pack, because one query (`audit/explore/Dependencies.ql`) reuses a
148
+
`Metrics.Dependencies` helper that ships with the upstream query pack rather than the standard
149
+
library. That's an extra surface area those two languages need to stay compatible with, which is
150
+
why the version table in each release shows an extra `codeql/<language>-queries` row for those two
151
+
languages that the others don't have.
138
152
139
153
## Releases & publishing
140
154
@@ -244,15 +258,13 @@ coding agent) in the loop for the hard part — fixing whatever the new CLI brea
244
258
[`copilot-setup-steps.yml`][copilot-setup-steps-workflow] pre-installs the pinned
245
259
CodeQL CLI and the matching `github/codeql` test-stubs checkout so the agent can
246
260
actually run `codeql test run` itself instead of guessing.
247
-
-[ ] Update the "Supported CodeQL versions" table above.
248
261
-[ ] Review and merge.
249
262
-[ ] Once merged, run [`update-release.yml`][update-release-workflow] as described in
250
263
[Cutting a release](#cutting-a-release) below to bump every pack's `version:` in
251
264
lockstep and trigger the real batch publish.
252
265
-**With `release_bump` set** — merging this PR *is* the release; there's no separate follow-up
253
266
step:
254
267
-[ ] Fix any compilation/test errors CI surfaces from upstream API changes, same as above.
255
-
-[ ] Update the "Supported CodeQL versions" table above.
256
268
-[ ] Review and merge — this alone triggers the real batch publish and the same
257
269
`summary` job / GitHub Release upsert described in
258
270
[Cutting a release](#cutting-a-release) below.
@@ -406,6 +418,8 @@ Please do get in touch (privacy@github.com) if you have any questions about this
0 commit comments