From ab41e09f86b8f0d09a271a6a8cb37e5f54f2ddcc Mon Sep 17 00:00:00 2001 From: Chad Bentz <1760475+felickz@users.noreply.github.com> Date: Mon, 6 Jul 2026 17:43:59 -0400 Subject: [PATCH 1/5] docs: document the current release/publish process in CONTRIBUTING.md Add a "Releases & publishing" section describing how things actually work today, as checkbox checklists rather than prose: - Shipping a change to a query/library pack: publish.yml only publishes a pack when its qlpack.yml `version:` differs from what's on GHCR, so merging alone never publishes anything - a version bump is a required manual step. - Updating the pinned CodeQL CLI/library version: also fully manual today (.codeqlversion bump, `codeql pack upgrade` per pack, fixing breakage, bumping affected pack versions). Notes that the current v2.21.1 update split this across #124 (dependency refresh) and #126 (still-open pack version bump PR) as a live example of the gap. - What GitHub Releases are for: clarifies .release.yml/update-release.yml and the Releases tab are a separate, decoupled, manual changelog process - and that they're currently out of sync with what's actually published on GHCR. This documents the process as it exists today; no new automation, scripts, or workflows are introduced. Kept intentionally minimal per feedback that a heavier automation-first pass (branch release-process-health-roadmap / PR #156) should stay a separate, future option rather than ship alongside this doc update. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5e8667a1..4c642d0e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -85,6 +85,85 @@ Most of our query packs only depend on the standard library (`*-all`) for CodeQL > [!NOTE] > 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). +## Releases & publishing + +Publishing a package to the GitHub Container Registry (GHCR) and creating a GitHub Release are two +**separate, decoupled** processes in this repository. This section documents the actual, current +process for each — most of it is manual today. + +### Shipping a change to a query/library pack + +[`publish.yml`][publish-workflow] runs on every push to `main`. For each pack it ships (`src` +queries, `lib` libraries, and — for `csharp`/`java` only today, see [#144][pr-144] — `ext` +extensions and `ext-library-sources`), it compares the `version:` in that pack's `qlpack.yml` on +`main` to the version currently published on [GHCR][ghcr-packages], and only publishes if they +differ. **Merging a change alone does not publish it** — the pack's own version must also be +bumped, or the change sits on `main` unpublished indefinitely. + +To ship a change: + +- [ ] Make your `` query/library change (e.g. edit files under `/src`). +- [ ] Bump `version:` in `/src/qlpack.yml` (or `lib`/`ext`/`ext-library-sources`, whichever + pack you changed), following [semver](https://semver.org/). +- [ ] If you changed a pack that other packs depend on (e.g. `/ext`), check whether + dependents pin an exact version of it (e.g. `/lib/qlpack.yml`) and bump that pin too + — these can drift out of sync otherwise (see [#155][pr-155]). +- [ ] Open a PR and get it reviewed/merged to `main`. +- [ ] Nothing further to do — `publish.yml` detects the version diff and publishes automatically on + merge. There's no separate "publish" button or manual trigger step for a version that's + already bumped. + +There is no in-repo inventory of "what's currently published" today — check the +[GHCR Packages page][ghcr-packages] for this repo directly, or compare against the `version:` field +in each language's `qlpack.yml` on `main` to see what will publish next. + +### Updating the pinned CodeQL CLI/library version + +Bumping the CodeQL CLI/library version this repo builds against (tracked in +[`.codeqlversion`][codeqlversion], see [Supported CodeQL versions](#supported-codeql-versions) +above) is also a fully manual process today. Nothing currently detects new upstream CodeQL CLI +releases automatically — a maintainer has to notice one exists and kick off this checklist by hand +(see [#118][pr-118] for an open proposal to at least automate the `codeql pack upgrade` step): + +- [ ] Update `.codeqlversion` to the new CLI version. +- [ ] Run `codeql pack upgrade ` for each pack directory to refresh its `codeql-pack.lock.yml`. +- [ ] Fix any compilation/test errors caused by upstream API changes (usually the hardest part — see + [#124][pr-124] for an example of what this can involve). +- [ ] Bump the `version:` field of every pack that changed, so the "Shipping a change" steps above + actually publish the update. +- [ ] Update the "Supported CodeQL versions" table above. +- [ ] Open a PR and get it reviewed/merged. + +> [!NOTE] +> The `.codeqlversion` bump and the pack version bumps don't have to land in the same PR — the +> current `v2.21.1` update split them: [#124][pr-124] refreshed dependencies/lock files for the new +> CLI, and [#126][pr-126] is a separate, still-open PR bumping every pack's `version:` so that change +> actually ships (per the [previous section](#shipping-a-change-to-a-querylibrary-pack)). If you split +> your update the same way, don't forget the second PR — that's exactly the gap `codeql pack upgrade` +> alone won't close. + +### What GitHub Releases are for + +The [Releases][releases] tab (`v0.2.0`, `v0.2.1`, ...) is a **repo-wide changelog**, unrelated to the +per-pack publishing described above: + +- [`.release.yml`][release-config] is config for the [`42ByteLabs/patch-release-me`][patch-release-me] + tool. It tracks a single repository-wide `version:` and, when bumped, patches version references in + `configs/*.yml` and dependency pins in `**/qlpack.yml` — it does **not** bump any pack's own + top-level `version:` field. +- [`update-release.yml`][update-release-workflow] is a manual `workflow_dispatch` (pick + patch/minor/major) that runs that tool and opens a PR with the bumped `.release.yml` and patched + references. +- The GitHub Release itself is created manually afterwards by a maintainer via GitHub's "Draft a new + release" UI with auto-generated notes. + +> [!NOTE] +> These two systems are currently out of sync: `.release.yml`'s `version:` is still `0.2.0`, and the +> latest GitHub Release is `v0.2.1`, while individual packs (e.g. `codeql-java-queries`) are already +> published at `0.2.2`. Don't use the Releases tab or `.release.yml` to infer what's currently +> published — check [GHCR][ghcr-packages] or a pack's `qlpack.yml` directly, per "Shipping a change" +> above. + ## Using your personal data If you contribute to this project, we will record your name and email address (as provided by you with your contributions) as part of the code repositories, which are public. We might also use this information to contact you in relation to your contributions, as well as in the normal course of software development. We also store records of CLA agreements signed in the past, but no longer require contributors to sign a CLA. Under GDPR legislation, we do this on the basis of our legitimate interest in creating the CodeQL product. @@ -94,3 +173,14 @@ Please do get in touch (privacy@github.com) if you have any questions about this [codeqlversion]: ./.codeqlversion +[publish-workflow]: ./.github/workflows/publish.yml +[update-release-workflow]: ./.github/workflows/update-release.yml +[release-config]: ./.release.yml +[patch-release-me]: https://github.com/42ByteLabs/patch-release-me +[releases]: https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/releases +[ghcr-packages]: https://github.com/orgs/GitHubSecurityLab/packages?repo_name=CodeQL-Community-Packs +[pr-118]: https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/pull/118 +[pr-124]: https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/pull/124 +[pr-126]: https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/pull/126 +[pr-144]: https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/pull/144 +[pr-155]: https://github.com/GitHubSecurityLab/CodeQL-Community-Packs/pull/155 From 353e00d2f69ad0c1159a0bee56e044a66eb0a034 Mon Sep 17 00:00:00 2001 From: Chad Bentz <1760475+felickz@users.noreply.github.com> Date: Mon, 6 Jul 2026 17:45:02 -0400 Subject: [PATCH 2/5] docs: clarify publish.yml is per-language/pack-type independent Each x combination (queries/lib/ext/ext-library-sources) is checked and published completely independently in publish.yml - touching one language's pack only requires bumping that pack's own version, not any other language or pack type. Added an explicit callout plus inline notes in the checklist so this isn't ambiguous. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 35 +++++++++++++++++++++++++---------- 1 file changed, 25 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4c642d0e..f4594199 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -93,25 +93,40 @@ process for each — most of it is manual today. ### Shipping a change to a query/library pack -[`publish.yml`][publish-workflow] runs on every push to `main`. For each pack it ships (`src` -queries, `lib` libraries, and — for `csharp`/`java` only today, see [#144][pr-144] — `ext` -extensions and `ext-library-sources`), it compares the `version:` in that pack's `qlpack.yml` on -`main` to the version currently published on [GHCR][ghcr-packages], and only publishes if they -differ. **Merging a change alone does not publish it** — the pack's own version must also be -bumped, or the change sits on `main` unpublished indefinitely. +[`publish.yml`][publish-workflow] runs on every push to `main`. It's organized as four jobs — one +per pack type (`queries` for `src`, `library` for `lib`, `extensions` for `ext`, +`library_sources_extensions` for `ext-library-sources`) — each matrixed over every language that has +that pack type (`ext`/`ext-library-sources` only run for `csharp`/`java` today, see [#144][pr-144]). + +**Each `` × `` combination is checked and published completely +independently.** For every matrix entry, the job compares the `version:` in that one pack's +`qlpack.yml` on `main` to the version currently published on [GHCR][ghcr-packages], and only +installs + publishes *that specific pack* if they differ — it never touches any other language or +pack type. Concretely, this means: + +- **You only need to bump the version of the pack(s) you actually changed.** If your PR only + touches `java/src`, bumping `java/src/qlpack.yml`'s version is enough — you do not need to touch + `csharp`, `go`, `python`, or any other language/pack type for `codeql-java-queries` to publish. +- **Nothing cascades automatically.** If a single PR changes both `java/src` and `csharp/lib`, each + needs its own version bump — bumping one does not publish the other, and bumping neither means + neither publishes. +- **Merging a change alone does not publish it.** The workflow runs on every merge, but a pack's own + `version:` field must have changed since the last publish, or that pack's matrix entry does nothing + and the change sits on `main` unpublished indefinitely. To ship a change: - [ ] Make your `` query/library change (e.g. edit files under `/src`). - [ ] Bump `version:` in `/src/qlpack.yml` (or `lib`/`ext`/`ext-library-sources`, whichever - pack you changed), following [semver](https://semver.org/). + pack you changed), following [semver](https://semver.org/). Only bump the specific pack(s) you + changed — other languages/pack types are unaffected and don't need touching. - [ ] If you changed a pack that other packs depend on (e.g. `/ext`), check whether dependents pin an exact version of it (e.g. `/lib/qlpack.yml`) and bump that pin too — these can drift out of sync otherwise (see [#155][pr-155]). - [ ] Open a PR and get it reviewed/merged to `main`. -- [ ] Nothing further to do — `publish.yml` detects the version diff and publishes automatically on - merge. There's no separate "publish" button or manual trigger step for a version that's - already bumped. +- [ ] Nothing further to do — `publish.yml` detects the version diff for that pack and publishes it + automatically on merge. There's no separate "publish" button or manual trigger step for a + version that's already bumped. There is no in-repo inventory of "what's currently published" today — check the [GHCR Packages page][ghcr-packages] for this repo directly, or compare against the `version:` field From 16b911cc08af9ab380de2767c503af09451d066e Mon Sep 17 00:00:00 2001 From: Chad Bentz <1760475+felickz@users.noreply.github.com> Date: Tue, 7 Jul 2026 12:59:32 -0400 Subject: [PATCH 3/5] docs: correct release-process claims with confirmed repo state - Clarify #126 (bump-all-packs) has sat unmerged since Apr 2025, predating #124's CLI 2.21.1 refresh - so only java has actually published 2.21.1-era content; other 6 languages' GHCR packages are still stale. - Clarify the .release.yml configs/*.yml pattern is dead (never matched in repo history) and the libs: pin pattern only applies to 5/7 langs. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f4594199..3136cbda 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -149,13 +149,16 @@ releases automatically — a maintainer has to notice one exists and kick off th - [ ] Update the "Supported CodeQL versions" table above. - [ ] Open a PR and get it reviewed/merged. -> [!NOTE] -> The `.codeqlversion` bump and the pack version bumps don't have to land in the same PR — the -> current `v2.21.1` update split them: [#124][pr-124] refreshed dependencies/lock files for the new -> CLI, and [#126][pr-126] is a separate, still-open PR bumping every pack's `version:` so that change -> actually ships (per the [previous section](#shipping-a-change-to-a-querylibrary-pack)). If you split -> your update the same way, don't forget the second PR — that's exactly the gap `codeql pack upgrade` -> alone won't close. +> [!WARNING] +> The `.codeqlversion` bump and the pack version bumps don't have to land in the same PR, but skipping +> the second one has real consequences: [#124][pr-124] refreshed `.codeqlversion` and every +> language's dependencies/lock files for `v2.21.1` back in June 2025, but bumped **no** pack +> `version:` fields. [#126][pr-126] — a separate PR that bumps every pack's `version:` — has sat open +> and unmerged since April 2025. As a result, only `java` (bumped separately, for an unrelated reason) +> has actually published `v2.21.1`-era content; the other six languages' packages on +> [GHCR][ghcr-packages] are still the versions published before that update and don't yet reflect it. +> Don't assume a merged dependency-refresh PR means consumers received it — check the pack actually +> published a new `version:` too. ### What GitHub Releases are for @@ -163,9 +166,12 @@ The [Releases][releases] tab (`v0.2.0`, `v0.2.1`, ...) is a **repo-wide changelo per-pack publishing described above: - [`.release.yml`][release-config] is config for the [`42ByteLabs/patch-release-me`][patch-release-me] - tool. It tracks a single repository-wide `version:` and, when bumped, patches version references in - `configs/*.yml` and dependency pins in `**/qlpack.yml` — it does **not** bump any pack's own - top-level `version:` field. + tool. It tracks a single repository-wide `version:` and defines two patch locations: one targeting + `configs/*.yml` (has never matched anything in this repo's history — those configs never pin an + exact version, so this is effectively dead), and one targeting the exact `codeql--libs:` + dependency pin in `**/qlpack.yml` (only 5 of 7 languages — cpp, go, javascript, python, ruby — pin an + exact version there; csharp/java use `'*'`). Either way, it does **not** bump any pack's own + top-level `version:` field, so bumping it alone doesn't publish anything. - [`update-release.yml`][update-release-workflow] is a manual `workflow_dispatch` (pick patch/minor/major) that runs that tool and opens a PR with the bumped `.release.yml` and patched references. From bca1d27b3518ab5aa042b2922acb9586d03a5eb7 Mon Sep 17 00:00:00 2001 From: Chad Bentz <1760475+felickz@users.noreply.github.com> Date: Tue, 7 Jul 2026 13:02:18 -0400 Subject: [PATCH 4/5] docs: address review feedback - avoid hardcoding volatile PR/version state - Rephrase pack-directory checklist item to list pack roots explicitly instead of mixing a generic notion with one example path. - Recast the #124/#126 note as a historical lesson instead of asserting #126's current PR state (which will go stale once it merges/closes). - Describe the release/publish version drift conceptually instead of citing specific version numbers that will rot as things change. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3136cbda..fe856b95 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -116,10 +116,12 @@ pack type. Concretely, this means: To ship a change: -- [ ] Make your `` query/library change (e.g. edit files under `/src`). -- [ ] Bump `version:` in `/src/qlpack.yml` (or `lib`/`ext`/`ext-library-sources`, whichever - pack you changed), following [semver](https://semver.org/). Only bump the specific pack(s) you - changed — other languages/pack types are unaffected and don't need touching. +- [ ] Make your change in the pack directory you intend to publish: `/src` (queries), + `/lib` (library), or `/ext`/`/ext-library-sources` (extensions, + `csharp`/`java` only). +- [ ] Bump `version:` in that pack's `qlpack.yml`, following [semver](https://semver.org/). Only bump + the specific pack(s) you changed — other languages/pack types are unaffected and don't need + touching. - [ ] If you changed a pack that other packs depend on (e.g. `/ext`), check whether dependents pin an exact version of it (e.g. `/lib/qlpack.yml`) and bump that pin too — these can drift out of sync otherwise (see [#155][pr-155]). @@ -150,15 +152,13 @@ releases automatically — a maintainer has to notice one exists and kick off th - [ ] Open a PR and get it reviewed/merged. > [!WARNING] -> The `.codeqlversion` bump and the pack version bumps don't have to land in the same PR, but skipping -> the second one has real consequences: [#124][pr-124] refreshed `.codeqlversion` and every -> language's dependencies/lock files for `v2.21.1` back in June 2025, but bumped **no** pack -> `version:` fields. [#126][pr-126] — a separate PR that bumps every pack's `version:` — has sat open -> and unmerged since April 2025. As a result, only `java` (bumped separately, for an unrelated reason) -> has actually published `v2.21.1`-era content; the other six languages' packages on -> [GHCR][ghcr-packages] are still the versions published before that update and don't yet reflect it. -> Don't assume a merged dependency-refresh PR means consumers received it — check the pack actually -> published a new `version:` too. +> The `.codeqlversion` bump and the pack version bumps don't have to land in the same PR — but +> splitting them is risky: [#124][pr-124] refreshed `.codeqlversion` and every language's +> dependencies/lock files for `v2.21.1`, without bumping any pack's `version:` field in the same PR. +> The companion PR to bump every pack's `version:` ([#126][pr-126]) went unmerged for a long stretch +> afterward, during which most languages' published GHCR packages silently kept serving pre-`v2.21.1` +> content even though `main` had already moved on. Don't assume a merged dependency-refresh PR means +> consumers received it — check that the pack's `version:` actually changed and published too. ### What GitHub Releases are for @@ -179,11 +179,11 @@ per-pack publishing described above: release" UI with auto-generated notes. > [!NOTE] -> These two systems are currently out of sync: `.release.yml`'s `version:` is still `0.2.0`, and the -> latest GitHub Release is `v0.2.1`, while individual packs (e.g. `codeql-java-queries`) are already -> published at `0.2.2`. Don't use the Releases tab or `.release.yml` to infer what's currently -> published — check [GHCR][ghcr-packages] or a pack's `qlpack.yml` directly, per "Shipping a change" -> above. +> These systems have no mechanism keeping them in sync, and have drifted in practice: `.release.yml`'s +> `version:`, the latest GitHub Release tag, and individual packs' published `version:` fields can all +> disagree with each other at any given time. Don't use the Releases tab or `.release.yml` to infer +> what's currently published — check [GHCR][ghcr-packages] or a pack's `qlpack.yml` directly, per +> "Shipping a change" above. ## Using your personal data From e2fc26da4f6edbd6a2386f4a17c9fe164991a5da Mon Sep 17 00:00:00 2001 From: Chad Bentz <1760475+felickz@users.noreply.github.com> Date: Tue, 7 Jul 2026 13:06:37 -0400 Subject: [PATCH 5/5] docs: remove em-dashes, use standard punctuation Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fe856b95..b0e282f4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,11 +62,11 @@ After the query is merged, we welcome pull requests to improve it. ## Supported CodeQL versions -Every query pack in this repository is compiled and tested against a specific version 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). +Every query pack in this repository is compiled and tested against a specific version 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). The pinning is codified in two places per language: -- [`.codeqlversion`][codeqlversion] (repo root) — the CodeQL **CLI** version CI installs and compiles/tests against. -- `/src/codeql-pack.lock.yml` — the exact resolved (locked) version of `codeql/-all` and its transitive dependencies, generated by `codeql pack install` against the CLI above. The `qlpack.yml` files themselves only declare an unpinned `'*'` range, so the lock file — not the qlpack.yml — is the real source of truth. +- [`.codeqlversion`][codeqlversion] (repo root): the CodeQL **CLI** version CI installs and compiles/tests against. +- `/src/codeql-pack.lock.yml`: the exact resolved (locked) version of `codeql/-all` and its transitive dependencies, generated by `codeql pack install` against the CLI above. The `qlpack.yml` files themselves only declare an unpinned `'*'` range, so the lock file, not the qlpack.yml, is the real source of truth. CodeQL CLI: `v2.21.1` (released 2025-04-16) ([Bundle](https://github.com/github/codeql-action/releases/tag/codeql-bundle-v2.21.1) / [Binary](https://github.com/github/codeql-cli-binaries/releases/tag/v2.21.1)) @@ -89,26 +89,26 @@ Most of our query packs only depend on the standard library (`*-all`) for CodeQL Publishing a package to the GitHub Container Registry (GHCR) and creating a GitHub Release are two **separate, decoupled** processes in this repository. This section documents the actual, current -process for each — most of it is manual today. +process for each; most of it is manual today. ### Shipping a change to a query/library pack -[`publish.yml`][publish-workflow] runs on every push to `main`. It's organized as four jobs — one +[`publish.yml`][publish-workflow] runs on every push to `main`. It's organized as four jobs: one per pack type (`queries` for `src`, `library` for `lib`, `extensions` for `ext`, -`library_sources_extensions` for `ext-library-sources`) — each matrixed over every language that has +`library_sources_extensions` for `ext-library-sources`), each matrixed over every language that has that pack type (`ext`/`ext-library-sources` only run for `csharp`/`java` today, see [#144][pr-144]). **Each `` × `` combination is checked and published completely independently.** For every matrix entry, the job compares the `version:` in that one pack's `qlpack.yml` on `main` to the version currently published on [GHCR][ghcr-packages], and only -installs + publishes *that specific pack* if they differ — it never touches any other language or +installs + publishes *that specific pack* if they differ. It never touches any other language or pack type. Concretely, this means: - **You only need to bump the version of the pack(s) you actually changed.** If your PR only - touches `java/src`, bumping `java/src/qlpack.yml`'s version is enough — you do not need to touch + touches `java/src`, bumping `java/src/qlpack.yml`'s version is enough; you do not need to touch `csharp`, `go`, `python`, or any other language/pack type for `codeql-java-queries` to publish. - **Nothing cascades automatically.** If a single PR changes both `java/src` and `csharp/lib`, each - needs its own version bump — bumping one does not publish the other, and bumping neither means + needs its own version bump: bumping one does not publish the other, and bumping neither means neither publishes. - **Merging a change alone does not publish it.** The workflow runs on every merge, but a pack's own `version:` field must have changed since the last publish, or that pack's matrix entry does nothing @@ -120,17 +120,17 @@ To ship a change: `/lib` (library), or `/ext`/`/ext-library-sources` (extensions, `csharp`/`java` only). - [ ] Bump `version:` in that pack's `qlpack.yml`, following [semver](https://semver.org/). Only bump - the specific pack(s) you changed — other languages/pack types are unaffected and don't need + the specific pack(s) you changed; other languages/pack types are unaffected and don't need touching. - [ ] If you changed a pack that other packs depend on (e.g. `/ext`), check whether dependents pin an exact version of it (e.g. `/lib/qlpack.yml`) and bump that pin too - — these can drift out of sync otherwise (see [#155][pr-155]). + (these can drift out of sync otherwise, see [#155][pr-155]). - [ ] Open a PR and get it reviewed/merged to `main`. -- [ ] Nothing further to do — `publish.yml` detects the version diff for that pack and publishes it +- [ ] Nothing further to do: `publish.yml` detects the version diff for that pack and publishes it automatically on merge. There's no separate "publish" button or manual trigger step for a version that's already bumped. -There is no in-repo inventory of "what's currently published" today — check the +There is no in-repo inventory of "what's currently published" today; check the [GHCR Packages page][ghcr-packages] for this repo directly, or compare against the `version:` field in each language's `qlpack.yml` on `main` to see what will publish next. @@ -139,12 +139,12 @@ in each language's `qlpack.yml` on `main` to see what will publish next. Bumping the CodeQL CLI/library version this repo builds against (tracked in [`.codeqlversion`][codeqlversion], see [Supported CodeQL versions](#supported-codeql-versions) above) is also a fully manual process today. Nothing currently detects new upstream CodeQL CLI -releases automatically — a maintainer has to notice one exists and kick off this checklist by hand +releases automatically. A maintainer has to notice one exists and kick off this checklist by hand (see [#118][pr-118] for an open proposal to at least automate the `codeql pack upgrade` step): - [ ] Update `.codeqlversion` to the new CLI version. - [ ] Run `codeql pack upgrade ` for each pack directory to refresh its `codeql-pack.lock.yml`. -- [ ] Fix any compilation/test errors caused by upstream API changes (usually the hardest part — see +- [ ] Fix any compilation/test errors caused by upstream API changes (usually the hardest part, see [#124][pr-124] for an example of what this can involve). - [ ] Bump the `version:` field of every pack that changed, so the "Shipping a change" steps above actually publish the update. @@ -152,13 +152,13 @@ releases automatically — a maintainer has to notice one exists and kick off th - [ ] Open a PR and get it reviewed/merged. > [!WARNING] -> The `.codeqlversion` bump and the pack version bumps don't have to land in the same PR — but +> The `.codeqlversion` bump and the pack version bumps don't have to land in the same PR, but > splitting them is risky: [#124][pr-124] refreshed `.codeqlversion` and every language's > dependencies/lock files for `v2.21.1`, without bumping any pack's `version:` field in the same PR. > The companion PR to bump every pack's `version:` ([#126][pr-126]) went unmerged for a long stretch > afterward, during which most languages' published GHCR packages silently kept serving pre-`v2.21.1` > content even though `main` had already moved on. Don't assume a merged dependency-refresh PR means -> consumers received it — check that the pack's `version:` actually changed and published too. +> consumers received it. Check that the pack's `version:` actually changed and published too. ### What GitHub Releases are for @@ -167,9 +167,9 @@ per-pack publishing described above: - [`.release.yml`][release-config] is config for the [`42ByteLabs/patch-release-me`][patch-release-me] tool. It tracks a single repository-wide `version:` and defines two patch locations: one targeting - `configs/*.yml` (has never matched anything in this repo's history — those configs never pin an + `configs/*.yml` (has never matched anything in this repo's history; those configs never pin an exact version, so this is effectively dead), and one targeting the exact `codeql--libs:` - dependency pin in `**/qlpack.yml` (only 5 of 7 languages — cpp, go, javascript, python, ruby — pin an + dependency pin in `**/qlpack.yml` (only 5 of 7 languages, cpp, go, javascript, python, ruby, pin an exact version there; csharp/java use `'*'`). Either way, it does **not** bump any pack's own top-level `version:` field, so bumping it alone doesn't publish anything. - [`update-release.yml`][update-release-workflow] is a manual `workflow_dispatch` (pick @@ -182,7 +182,7 @@ per-pack publishing described above: > These systems have no mechanism keeping them in sync, and have drifted in practice: `.release.yml`'s > `version:`, the latest GitHub Release tag, and individual packs' published `version:` fields can all > disagree with each other at any given time. Don't use the Releases tab or `.release.yml` to infer -> what's currently published — check [GHCR][ghcr-packages] or a pack's `qlpack.yml` directly, per +> what's currently published. Check [GHCR][ghcr-packages] or a pack's `qlpack.yml` directly, per > "Shipping a change" above. ## Using your personal data