From 39f1b3fa8d8dee53e188d34abe2f6aaad7216cfb Mon Sep 17 00:00:00 2001 From: Mario Campos Date: Wed, 7 Oct 2026 13:11:34 -0500 Subject: [PATCH 1/8] Document change-notes process --- CONTRIBUTING.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 216097f893..fac24c3d4e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -53,6 +53,7 @@ Here are a few things you can do that will increase the likelihood of your pull - Write tests. - Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests. - Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). +- For user-facing changes, add a [change-note](#change-notes). ## Releasing (write access required) @@ -129,6 +130,57 @@ To deprecate an older version of the Action: 1. Upgrade the Actions warning for customers using the deprecated version to a non-fatal error, and mention that this version of the Action is no longer supported. 1. Make a PR to bump the `OLDEST_SUPPORTED_MAJOR_VERSION` in [config.ts](pr-checks/config.ts). Once this PR is merged, the release process will no longer backport changes to the deprecated release version. +## Change-notes + +Change-notes are Markdown files used to document user-facing changes. When making a change that affects users, create a change-note file in `unreleased-change-notes/` that describes the change. At the next release, the change-note files in `unreleased-change-notes/` will be combined into a new entry in `CHANGELOG.md`. + +### Change-note file format + +Change-note files must follow a certain format so that they can be automatically validated and processed. Failure to follow the format will result in a failed PR check. + +You may validate your change-note file locally by running `npx tsx pr-checks/changenotes.ts validate`. This command will scan all change-note files in `unreleased-change-notes/` and report any errors. + +#### File name + +Change-note files must be named according to the following pattern: `YYYY-MM-DD-.md`, where `YYYY-MM-DD` is the date of the change and `` is a short non-spaced description of the change. For example, a change-note file for a JSON-related bug fix that was made on January 1st, 2020 might be named `2020-01-01-fix-json-bug.md`. + +#### Frontmatter + +The first line of the file must be a YAML frontmatter block, which is delimited by lines containing three dashes (`---`). The frontmatter block must contain a single `category` field, whose value must be one of the following categories: + +| Category | Description | +| -------- | ----------- | +| `breaking` | A change that introduces backward-incompatible behavior. | +| `feature` | A new capability or behavior added to the Action. | +| `improvement` | An enhancement to existing functionality or performance. | +| `securityFix` | A change that addresses a security vulnerability. | +| `fix` | A bug fix that corrects unexpected behavior. | +| `unship` | Features or options that have been removed. | +| `deprecation` | Deprecation of features that will be removed in future versions. | +| `knownIssue` | A known issue or limitation in the current release. | +| `misc` | Other changes that do not fit into other categories. | + +#### Body + +The body of the change-note file must: + +- Be written in valid [GitHub-Flavored Markdown](https://github.github.com/gfm/). +- Describe the change in a way that is understandable to users of the Action. Limit the description to 1-2 sentences, and avoid technical details that are not relevant to users. +- Be structured as a single unordered Markdown list with hyphen (`-`) bullets. Each list item should describe a single change. If there are multiple changes, use multiple list items. + +### Example change-note file + +``` +--- +category: feature +--- + +- Added support for the SARIF v2.2 specification in the `github/codeql-action/upload` Action. +- Added a new `sarif-version` input to the `github/codeql-action/upload` Action, allowing users to specify the SARIF version to use when uploading results. +``` + + + ## Resources - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) From 38fee79b02b7416b7510f1db2bb7c395df5dd4d5 Mon Sep 17 00:00:00 2001 From: Mario Campos Date: Wed, 7 Oct 2026 15:21:38 -0500 Subject: [PATCH 2/8] Specify allowed characters in change-note filename --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fac24c3d4e..dd0b4886b4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -142,7 +142,7 @@ You may validate your change-note file locally by running `npx tsx pr-checks/cha #### File name -Change-note files must be named according to the following pattern: `YYYY-MM-DD-.md`, where `YYYY-MM-DD` is the date of the change and `` is a short non-spaced description of the change. For example, a change-note file for a JSON-related bug fix that was made on January 1st, 2020 might be named `2020-01-01-fix-json-bug.md`. +Change-note files must be named according to the following pattern: `YYYY-MM-DD-.md`, where `YYYY-MM-DD` is the date of the change and `` is a short description of the change. The `` must contain only lowercase letters (`a-z`), digits (`0-9`), and hyphens (`-`), and must start with a letter or digit. Hyphens may be used to separate words. For example, a change-note file for a JSON-related bug fix that was made on January 1st, 2020 might be named `2020-01-01-fix-json-bug.md`. #### Frontmatter From 2a935ca93d4a319794c6294a9379ecbeb336d32c Mon Sep 17 00:00:00 2001 From: Mario Campos Date: Thu, 8 Oct 2026 12:48:24 -0500 Subject: [PATCH 3/8] Move change-note documentation to `unreleased-change-notes/README.md` --- CONTRIBUTING.md | 53 +------------------------------ unreleased-change-notes/README.md | 48 ++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+), 52 deletions(-) create mode 100644 unreleased-change-notes/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dd0b4886b4..1436c9bb3c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -53,7 +53,7 @@ Here are a few things you can do that will increase the likelihood of your pull - Write tests. - Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests. - Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). -- For user-facing changes, add a [change-note](#change-notes). +- For user-facing changes, add a change-note file. See [unreleased-change-notes/README.md](unreleased-change-notes/README.md). ## Releasing (write access required) @@ -130,57 +130,6 @@ To deprecate an older version of the Action: 1. Upgrade the Actions warning for customers using the deprecated version to a non-fatal error, and mention that this version of the Action is no longer supported. 1. Make a PR to bump the `OLDEST_SUPPORTED_MAJOR_VERSION` in [config.ts](pr-checks/config.ts). Once this PR is merged, the release process will no longer backport changes to the deprecated release version. -## Change-notes - -Change-notes are Markdown files used to document user-facing changes. When making a change that affects users, create a change-note file in `unreleased-change-notes/` that describes the change. At the next release, the change-note files in `unreleased-change-notes/` will be combined into a new entry in `CHANGELOG.md`. - -### Change-note file format - -Change-note files must follow a certain format so that they can be automatically validated and processed. Failure to follow the format will result in a failed PR check. - -You may validate your change-note file locally by running `npx tsx pr-checks/changenotes.ts validate`. This command will scan all change-note files in `unreleased-change-notes/` and report any errors. - -#### File name - -Change-note files must be named according to the following pattern: `YYYY-MM-DD-.md`, where `YYYY-MM-DD` is the date of the change and `` is a short description of the change. The `` must contain only lowercase letters (`a-z`), digits (`0-9`), and hyphens (`-`), and must start with a letter or digit. Hyphens may be used to separate words. For example, a change-note file for a JSON-related bug fix that was made on January 1st, 2020 might be named `2020-01-01-fix-json-bug.md`. - -#### Frontmatter - -The first line of the file must be a YAML frontmatter block, which is delimited by lines containing three dashes (`---`). The frontmatter block must contain a single `category` field, whose value must be one of the following categories: - -| Category | Description | -| -------- | ----------- | -| `breaking` | A change that introduces backward-incompatible behavior. | -| `feature` | A new capability or behavior added to the Action. | -| `improvement` | An enhancement to existing functionality or performance. | -| `securityFix` | A change that addresses a security vulnerability. | -| `fix` | A bug fix that corrects unexpected behavior. | -| `unship` | Features or options that have been removed. | -| `deprecation` | Deprecation of features that will be removed in future versions. | -| `knownIssue` | A known issue or limitation in the current release. | -| `misc` | Other changes that do not fit into other categories. | - -#### Body - -The body of the change-note file must: - -- Be written in valid [GitHub-Flavored Markdown](https://github.github.com/gfm/). -- Describe the change in a way that is understandable to users of the Action. Limit the description to 1-2 sentences, and avoid technical details that are not relevant to users. -- Be structured as a single unordered Markdown list with hyphen (`-`) bullets. Each list item should describe a single change. If there are multiple changes, use multiple list items. - -### Example change-note file - -``` ---- -category: feature ---- - -- Added support for the SARIF v2.2 specification in the `github/codeql-action/upload` Action. -- Added a new `sarif-version` input to the `github/codeql-action/upload` Action, allowing users to specify the SARIF version to use when uploading results. -``` - - - ## Resources - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) diff --git a/unreleased-change-notes/README.md b/unreleased-change-notes/README.md new file mode 100644 index 0000000000..30b3789e43 --- /dev/null +++ b/unreleased-change-notes/README.md @@ -0,0 +1,48 @@ +## unreleased-change-notes + +Change-notes are Markdown files used to document user-facing changes. When making a change that affects users, create a change-note file here that describes the change. At the next release, the change-note files in `unreleased-change-notes/` will be combined into a new entry in `CHANGELOG.md`. + +### Change-note file format + +Change-note files must follow a certain format so that they can be automatically validated and processed. Failure to follow the format will result in a failed PR check. + +You may validate your change-note file locally by running `npx tsx pr-checks/changenotes.ts validate`. This command will scan all change-note files in `unreleased-change-notes/` and report any errors. + +#### File name + +Change-note files must be named according to the following pattern: `YYYY-MM-DD-.md`, where `YYYY-MM-DD` is the date of the change and `` is a short description of the change. The `` must contain only lowercase letters (`a-z`), digits (`0-9`), and hyphens (`-`), and must start with a letter or digit. Hyphens may be used to separate words. For example, a change-note file for a JSON-related bug fix that was made on January 1st, 2020 might be named `2020-01-01-fix-json-bug.md`. + +#### Frontmatter + +The first line of the file must be a YAML frontmatter block, which is delimited by lines containing three dashes (`---`). The frontmatter block must contain a single `category` field, whose value must be one of the following categories: + +| Category | Description | +| -------- | ----------- | +| `breaking` | A change that introduces backward-incompatible behavior. | +| `feature` | A new capability or behavior added to the Action. | +| `improvement` | An enhancement to existing functionality or performance. | +| `securityFix` | A change that addresses a security vulnerability. | +| `fix` | A bug fix that corrects unexpected behavior. | +| `unship` | Features or options that have been removed. | +| `deprecation` | Deprecation of features that will be removed in future versions. | +| `knownIssue` | A known issue or limitation in the current release. | +| `misc` | Other changes that do not fit into other categories. | + +#### Body + +The body of the change-note file must: + +- Be written in valid [GitHub-Flavored Markdown](https://github.github.com/gfm/). +- Describe the change in a way that is understandable to users of the Action. Limit the description to 1-2 sentences, and avoid technical details that are not relevant to users. +- Be structured as a single unordered Markdown list with hyphen (`-`) bullets. Each list item should describe a single change. If there are multiple changes, use multiple list items. + +### Example change-note file + +``` +--- +category: feature +--- + +- Added support for the SARIF v2.2 specification in the `github/codeql-action/upload` Action. +- Added a new `sarif-version` input to the `github/codeql-action/upload` Action, allowing users to specify the SARIF version to use when uploading results. +``` From 3acc10a2cec8c531ed3afd26489b8a377ffacba6 Mon Sep 17 00:00:00 2001 From: Mario Campos Date: Thu, 8 Oct 2026 12:53:37 -0500 Subject: [PATCH 4/8] Exclude `README.md` from change-note validation and assembly --- pr-checks/changenotes.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pr-checks/changenotes.ts b/pr-checks/changenotes.ts index 933d255cd5..26035527b5 100755 --- a/pr-checks/changenotes.ts +++ b/pr-checks/changenotes.ts @@ -28,12 +28,12 @@ interface ChangenoteFile { /** * Returns the absolute file paths of all files in - * {@link CHANGENOTES_DIR} (except ".gitkeep"). + * {@link CHANGENOTES_DIR} (except ".gitkeep" and "README.md"). * */ function listUnreleasedChangenoteDir(): string[] { return fs .readdirSync(CHANGENOTES_DIR) - .filter((name) => name !== ".gitkeep") + .filter((name) => ![".gitkeep", "README.md"].includes(name)) .map((name) => path.join(CHANGENOTES_DIR, name)); } From 40d76bc72746338d65640ffede693aee5bfb4fb6 Mon Sep 17 00:00:00 2001 From: Mario Campos Date: Thu, 8 Oct 2026 14:55:23 -0500 Subject: [PATCH 5/8] Use actual CHANGELOG.md entries for example change-note --- unreleased-change-notes/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/unreleased-change-notes/README.md b/unreleased-change-notes/README.md index 30b3789e43..cf19da0b46 100644 --- a/unreleased-change-notes/README.md +++ b/unreleased-change-notes/README.md @@ -40,9 +40,9 @@ The body of the change-note file must: ``` --- -category: feature +category: fix --- -- Added support for the SARIF v2.2 specification in the `github/codeql-action/upload` Action. -- Added a new `sarif-version` input to the `github/codeql-action/upload` Action, allowing users to specify the SARIF version to use when uploading results. +- Fixed a bug where a network error while streaming the download of the CodeQL bundle could terminate the `init` Action instead of falling back to downloading the bundle before extracting it. [#4061](https://github.com/github/codeql-action/pull/4061) +- Fix incorrect minimum required Git version for [improved incremental analysis](https://github.com/github/roadmap/issues/1158): it should have been 2.36.0, not 2.11.0. [#3781](https://github.com/github/codeql-action/pull/3781) ``` From cc826bb8e32ca6fbb030841ede3fdaec950ab2bd Mon Sep 17 00:00:00 2001 From: Mario Campos Date: Thu, 8 Oct 2026 14:57:03 -0500 Subject: [PATCH 6/8] Delete unnecessary guidance for change-note body --- unreleased-change-notes/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/unreleased-change-notes/README.md b/unreleased-change-notes/README.md index cf19da0b46..48ce5a3e15 100644 --- a/unreleased-change-notes/README.md +++ b/unreleased-change-notes/README.md @@ -33,7 +33,6 @@ The first line of the file must be a YAML frontmatter block, which is delimited The body of the change-note file must: - Be written in valid [GitHub-Flavored Markdown](https://github.github.com/gfm/). -- Describe the change in a way that is understandable to users of the Action. Limit the description to 1-2 sentences, and avoid technical details that are not relevant to users. - Be structured as a single unordered Markdown list with hyphen (`-`) bullets. Each list item should describe a single change. If there are multiple changes, use multiple list items. ### Example change-note file From 13b13216858f78c10bedda85055369d87f3ef35d Mon Sep 17 00:00:00 2001 From: Mario Campos Date: Thu, 8 Oct 2026 15:01:05 -0500 Subject: [PATCH 7/8] Refine misc. wording of `unreleased-change-notes/README.md` Co-authored-by: Michael B. Gale --- unreleased-change-notes/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/unreleased-change-notes/README.md b/unreleased-change-notes/README.md index 48ce5a3e15..d477a0b1b0 100644 --- a/unreleased-change-notes/README.md +++ b/unreleased-change-notes/README.md @@ -1,6 +1,6 @@ -## unreleased-change-notes +## Change notes -Change-notes are Markdown files used to document user-facing changes. When making a change that affects users, create a change-note file here that describes the change. At the next release, the change-note files in `unreleased-change-notes/` will be combined into a new entry in `CHANGELOG.md`. +Change-notes are Markdown files used to document user-facing changes. When making a change that affects users, create a markdown file here that describes the change. During the next release, the change-note files in `unreleased-change-notes/` will automatically be added to `CHANGELOG.md`. ### Change-note file format From fa56eef12fd72da6f01e786304612ce03ba93a48 Mon Sep 17 00:00:00 2001 From: Mario Campos Date: Fri, 9 Oct 2026 16:48:00 -0500 Subject: [PATCH 8/8] Delete unnecessary filename/frontmatter validation instructions --- unreleased-change-notes/README.md | 27 ++------------------------- 1 file changed, 2 insertions(+), 25 deletions(-) diff --git a/unreleased-change-notes/README.md b/unreleased-change-notes/README.md index d477a0b1b0..60778c7954 100644 --- a/unreleased-change-notes/README.md +++ b/unreleased-change-notes/README.md @@ -1,6 +1,6 @@ -## Change notes +## Change notes -Change-notes are Markdown files used to document user-facing changes. When making a change that affects users, create a markdown file here that describes the change. During the next release, the change-note files in `unreleased-change-notes/` will automatically be added to `CHANGELOG.md`. +Change-notes are Markdown files used to document user-facing changes. When making a change that affects users, create a Markdown file here that describes the change. During the next release, the change-note files in `unreleased-change-notes/` will automatically be added to `CHANGELOG.md`. ### Change-note file format @@ -8,25 +8,6 @@ Change-note files must follow a certain format so that they can be automatically You may validate your change-note file locally by running `npx tsx pr-checks/changenotes.ts validate`. This command will scan all change-note files in `unreleased-change-notes/` and report any errors. -#### File name - -Change-note files must be named according to the following pattern: `YYYY-MM-DD-.md`, where `YYYY-MM-DD` is the date of the change and `` is a short description of the change. The `` must contain only lowercase letters (`a-z`), digits (`0-9`), and hyphens (`-`), and must start with a letter or digit. Hyphens may be used to separate words. For example, a change-note file for a JSON-related bug fix that was made on January 1st, 2020 might be named `2020-01-01-fix-json-bug.md`. - -#### Frontmatter - -The first line of the file must be a YAML frontmatter block, which is delimited by lines containing three dashes (`---`). The frontmatter block must contain a single `category` field, whose value must be one of the following categories: - -| Category | Description | -| -------- | ----------- | -| `breaking` | A change that introduces backward-incompatible behavior. | -| `feature` | A new capability or behavior added to the Action. | -| `improvement` | An enhancement to existing functionality or performance. | -| `securityFix` | A change that addresses a security vulnerability. | -| `fix` | A bug fix that corrects unexpected behavior. | -| `unship` | Features or options that have been removed. | -| `deprecation` | Deprecation of features that will be removed in future versions. | -| `knownIssue` | A known issue or limitation in the current release. | -| `misc` | Other changes that do not fit into other categories. | #### Body @@ -38,10 +19,6 @@ The body of the change-note file must: ### Example change-note file ``` ---- -category: fix ---- - - Fixed a bug where a network error while streaming the download of the CodeQL bundle could terminate the `init` Action instead of falling back to downloading the bundle before extracting it. [#4061](https://github.com/github/codeql-action/pull/4061) - Fix incorrect minimum required Git version for [improved incremental analysis](https://github.com/github/roadmap/issues/1158): it should have been 2.36.0, not 2.11.0. [#3781](https://github.com/github/codeql-action/pull/3781) ```