docs: clarify how release/publish process works today#157
Merged
Conversation
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>
Each <language> x <pack type> 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>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new documentation section to CONTRIBUTING.md explaining how releases and GHCR pack publishing currently work in this repository, emphasizing the manual steps and the separation between GitHub Releases and pack publication.
Changes:
- Documented the current
publish.ymlbehavior and the per-pack version-bump requirement for GHCR publishing. - Added a checklist for updating the pinned CodeQL CLI/library version (including the need to bump affected pack versions to actually publish changes).
- Clarified the role of
.release.yml/update-release.ymland why GitHub Releases can be out of sync with what’s published to GHCR.
Show a summary per file
| File | Description |
|---|---|
| CONTRIBUTING.md | Adds a new “Releases & publishing” section describing the current manual publishing/release processes and related workflows/links. |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 3
- Review effort level: Low
- 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>
…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>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
Author
|
Bluntly documenting this as current state as many maintainers have left this project and I need to wrap my head around all the things. ⏩ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this is
A docs-only PR that documents the actual, current release/publish process in
CONTRIBUTING.mdas checkbox checklists: no new scripts, workflows, or automation. This is a lighter-weight alternative scoped to just clarifying today's manual process, split out from a heavier automation-first draft (#156) that's being left as a possible future option.New "Releases & publishing" section covers:
publish.ymlruns 4 independent jobs (queries/library/extensions/library_sources_extensions), each matrixed per-language. Each<language>x<pack type>combination is checked and published completely independently: it only compares/publishes that one pack's version vs. GHCR. Concretely:java/srconly requires bumpingjava/src/qlpack.yml, no need to touchcsharp,go,python, etc.).version:must change..codeqlversionbump,codeql pack upgradeper pack, fixing breakage, bumping affected pack versions). Uses the real, currentv2.21.1update (Update dependencies to packs shipped with 2.21.1 #124 dependency refresh and feat(version): v0.2.2 #126 pack version bump PR) as a historical example of how this can get split across PRs and why the second PR shouldn't be forgotten..release.yml/update-release.yml/the Releases tab are a separate, decoupled, manual changelog process, and notes they're currently out of sync with what's actually published on GHCR.Why split from #156
#156 bundles this doc update with new CI automation (version-bump-check safeguard, CodeQL release detection, published-version inventory). Good ideas, but heavier-handed than needed to answer "how does this actually work today." This PR lands the documentation on its own so it's easy to review/merge quickly; #156 remains open as a future option if we want to build out the automation later.