From 9f65419cf31ae53a326538b5ae08a96a406d59b7 Mon Sep 17 00:00:00 2001 From: Mario Campos Date: Tue, 21 Oct 2025 16:17:37 -0500 Subject: [PATCH 1/5] Add validation guide for query-pack change notes Added a validation guide for query-pack change notes, including file naming conventions, frontmatter requirements, and examples of valid and invalid entries. --- .../query-pack-change-notes.instructions.md | 116 ++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 .github/instructions/query-pack-change-notes.instructions.md diff --git a/.github/instructions/query-pack-change-notes.instructions.md b/.github/instructions/query-pack-change-notes.instructions.md new file mode 100644 index 000000000000..eaa4b44e4802 --- /dev/null +++ b/.github/instructions/query-pack-change-notes.instructions.md @@ -0,0 +1,116 @@ +--- +applyTo: > + actions/ql/src/change-notes/*.md, + cpp/ql/src/change-notes/*.md, + csharp/ql/src/change-notes/*.md, + go/ql/src/change-notes/*.md, + java/ql/src/change-notes/*.md, + javascript/ql/src/change-notes/*.md, + python/ql/src/change-notes/*.md, + ql/ql/src/change-notes/*.md, + ruby/ql/src/change-notes/*.md, + rust/ql/src/change-notes/*.md, + swift/ql/src/change-notes/*.md +--- + +# Validation guide for query-pack change notes + +When performing a code review, ensure that the Markdown change-notes in the pull request meet the following standards: + +## File name +The file name must match this pattern: `YYYY-MM-DD-description.md` +- `YYYY-MM-DD` should refer to the year, month, and day, respectively, of the change; +- `description` should refer to a short alphanumerical text, separated by hyphens, that describes the change-note; +- The extension should be ".md". + +### Examples +#### Valid + +- 2020-10-12-new-client-library.md +- 2025-01-01-refactored-database-logic.md +- 2022-12-25-removed-log4j.md + +#### Invalid + +- 3000-60-32-invalid-date.md +- no-date-in-file-name.md +- 2019-01-01 file name contains spaces.md + +## Frontmatter +The file must begin with YAML frontmatter. Valid YAML frontmatter properties include: + +- `category` + - Required + - This is a string that identifies one of a fixed set of categories that the change falls into. +- `tags` + - Optional + - A list of string tags. + +### Categories +| Category | Description | +|------------------|-------------| +| `breaking` | Any breaking change to the query pack, the most common of which is the deletion of an existing query. | +| `deprecated` | An existing query has been marked as `deprecated`. | +| `newQuery` | A new query has been added. | +| `queryMetadata` | The metadata of a query has been changed (e.g., to increase or reduce the `@precision`). | +| `majorAnalysis` | The set of results produced by a query has changed (fewer false positives, more true positives, etc.) enough to be noticed by users of the query pack. | +| `minorAnalysis` | The set of results produced by a query has changed, but only in scenarios that affect relatively few users. | +| `fix` | A fix that does not change the results reported by a query (e.g., a performance fix). | + +### Examples +#### Valid + +```yaml +--- +category: newQuery +--- +``` + +```yaml +--- +category: majorAnalysis +tags: cpp +--- +``` + +#### Invalid + +##### Missing `category` property + +```yaml +--- +tags: cpp +--- +``` + +##### Invalid category `bug`; use `fix` instead + +```yaml +--- +category: bug +--- +``` + +## Description +The content after the YAML frontmatter must be an American-English description of the change in one or more unordered Markdown list entries. + +### Examples + +#### Valid + +```markdown +* Added support for the Nim programming language. +``` + +#### Invalid + +##### Change description is not in a bullet-list entry +```markdown +Added support for the Nim programming language. +``` + +##### No headers; only list entries +```markdown +# Fixes +* Fixed C++ source parsing to handle comma operator. +``` From 1c2ee6e1e8dea546c52dba94992d96b865384989 Mon Sep 17 00:00:00 2001 From: Mario Campos Date: Tue, 21 Oct 2025 16:19:42 -0500 Subject: [PATCH 2/5] Add validation guide for library-pack change notes Added a validation guide for library-pack change notes, including file naming conventions, frontmatter requirements, and examples of valid and invalid entries. --- .../library-pack-change-notes.instructions.md | 123 ++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 .github/instructions/library-pack-change-notes.instructions.md diff --git a/.github/instructions/library-pack-change-notes.instructions.md b/.github/instructions/library-pack-change-notes.instructions.md new file mode 100644 index 000000000000..b79d090dfe94 --- /dev/null +++ b/.github/instructions/library-pack-change-notes.instructions.md @@ -0,0 +1,123 @@ +--- +applyTo: > + actions/ql/lib/change-notes/*.md, + cpp/ql/lib/change-notes/*.md, + csharp/ql/lib/change-notes/*.md, + go/ql/lib/change-notes/*.md, + java/ql/lib/change-notes/*.md, + javascript/ql/lib/change-notes/*.md, + python/ql/lib/change-notes/*.md, + ruby/ql/lib/change-notes/*.md, + rust/ql/lib/change-notes/*.md, + shared/mad/change-notes/*.md, + shared/quantum/change-notes/*.md, + shared/regex/change-notes/*.md, + shared/ssa/change-notes/*.md, + shared/typos/change-notes/*.md, + shared/util/change-notes/*.md, + shared/xml/change-notes/*.md, + shared/yaml/change-notes/*.md, + swift/ql/lib/change-notes/*.md +--- + +# Validation guide for library-pack change notes + +When performing a code review, ensure that the Markdown change-notes in the pull request meet the following standards: + +## File name +The file name must match this pattern: `YYYY-MM-DD-description.md` +- `YYYY-MM-DD` should refer to the year, month, and day, respectively, of the change; +- `description` should refer to a short alphanumerical text, separated by hyphens, that describes the change-note; +- The extension should be ".md". + +### Examples +#### Valid + +- 2020-10-12-new-client-library.md +- 2025-01-01-refactored-database-logic.md +- 2022-12-25-removed-log4j.md + +#### Invalid + +- 3000-60-32-invalid-date.md +- no-date-in-file-name.md +- 2019-01-01 file name contains spaces.md + +## Frontmatter +The file must begin with YAML frontmatter. Valid YAML frontmatter properties include: + +- `category` + - Required + - This is a string that identifies one of a fixed set of categories that the change falls into. +- `tags` + - Optional + - A list of string tags. + + +### Categories +| Category | Description | +|------------------|-------------| +| `breaking` | Any breaking change to the library pack, the most common of which is the deletion of an existing API. | +| `deprecated` | An existing API has been marked as deprecated. | +| `feature` | A new library API has been added. | +| `majorAnalysis` | An API has changed in a way that may affect the results produced by a query that consumes the API. | +| `minorAnalysis` | An API has changed in a way that may affect the results produced by a query that consumes the API, but only in scenarios that affect relatively few users. | +| `fix` | An API has been fixed in a way that is not likely to affect the results produced by a query that consumes the API. | + +### Examples +#### Valid + +```yaml +--- +category: feature +--- +``` + +```yaml +--- +category: majorAnalysis +tags: cpp +--- +``` + +#### Invalid + +##### Missing `category` property + +```yaml +--- +tags: cpp +--- +``` + +##### Invalid category `bug`; use `fix` instead + +```yaml +--- +category: bug +--- +``` + +## Description +The content after the YAML frontmatter must be an American-English description of the change in one or more unordered Markdown list entries. + +### Examples + +#### Valid + +```markdown +* Added support for the Nim programming language. +``` + +#### Invalid + +##### Change description is not in a bullet-list entry +```markdown +Added support for the Nim programming language. +``` + +##### No headers; only list entries +```markdown +# Fixes +* Fixed C++ source parsing to handle comma operator. +``` From 46b66b6866432621afb96da21a10a06d190aefd3 Mon Sep 17 00:00:00 2001 From: Mario Campos Date: Tue, 21 Oct 2025 22:44:09 +0000 Subject: [PATCH 3/5] Simplify applyTo globs in library- and query-pack change-notes instructions --- .../library-pack-change-notes.instructions.md | 20 +------------------ .../query-pack-change-notes.instructions.md | 13 +----------- 2 files changed, 2 insertions(+), 31 deletions(-) diff --git a/.github/instructions/library-pack-change-notes.instructions.md b/.github/instructions/library-pack-change-notes.instructions.md index b79d090dfe94..fd0f779cc65e 100644 --- a/.github/instructions/library-pack-change-notes.instructions.md +++ b/.github/instructions/library-pack-change-notes.instructions.md @@ -1,23 +1,5 @@ --- -applyTo: > - actions/ql/lib/change-notes/*.md, - cpp/ql/lib/change-notes/*.md, - csharp/ql/lib/change-notes/*.md, - go/ql/lib/change-notes/*.md, - java/ql/lib/change-notes/*.md, - javascript/ql/lib/change-notes/*.md, - python/ql/lib/change-notes/*.md, - ruby/ql/lib/change-notes/*.md, - rust/ql/lib/change-notes/*.md, - shared/mad/change-notes/*.md, - shared/quantum/change-notes/*.md, - shared/regex/change-notes/*.md, - shared/ssa/change-notes/*.md, - shared/typos/change-notes/*.md, - shared/util/change-notes/*.md, - shared/xml/change-notes/*.md, - shared/yaml/change-notes/*.md, - swift/ql/lib/change-notes/*.md +applyTo: "*/ql/lib/change-notes/*.md,shared/*/change-notes/*.md" --- # Validation guide for library-pack change notes diff --git a/.github/instructions/query-pack-change-notes.instructions.md b/.github/instructions/query-pack-change-notes.instructions.md index eaa4b44e4802..3b263436720f 100644 --- a/.github/instructions/query-pack-change-notes.instructions.md +++ b/.github/instructions/query-pack-change-notes.instructions.md @@ -1,16 +1,5 @@ --- -applyTo: > - actions/ql/src/change-notes/*.md, - cpp/ql/src/change-notes/*.md, - csharp/ql/src/change-notes/*.md, - go/ql/src/change-notes/*.md, - java/ql/src/change-notes/*.md, - javascript/ql/src/change-notes/*.md, - python/ql/src/change-notes/*.md, - ql/ql/src/change-notes/*.md, - ruby/ql/src/change-notes/*.md, - rust/ql/src/change-notes/*.md, - swift/ql/src/change-notes/*.md +applyTo: "*/ql/src/change-notes/*.md" --- # Validation guide for query-pack change notes From 8d8a8e045ef963f8740c4991454e1f74ea1182a2 Mon Sep 17 00:00:00 2001 From: Mario Campos Date: Tue, 21 Oct 2025 22:46:49 +0000 Subject: [PATCH 4/5] Instruct Copilot to suggest corrections in change notes --- .github/instructions/library-pack-change-notes.instructions.md | 2 +- .github/instructions/query-pack-change-notes.instructions.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/instructions/library-pack-change-notes.instructions.md b/.github/instructions/library-pack-change-notes.instructions.md index fd0f779cc65e..1df88fff3537 100644 --- a/.github/instructions/library-pack-change-notes.instructions.md +++ b/.github/instructions/library-pack-change-notes.instructions.md @@ -4,7 +4,7 @@ applyTo: "*/ql/lib/change-notes/*.md,shared/*/change-notes/*.md" # Validation guide for library-pack change notes -When performing a code review, ensure that the Markdown change-notes in the pull request meet the following standards: +When reviewing change notes in a pull request, ensure that they meet the following standards. Suggest changes if necessary. ## File name The file name must match this pattern: `YYYY-MM-DD-description.md` diff --git a/.github/instructions/query-pack-change-notes.instructions.md b/.github/instructions/query-pack-change-notes.instructions.md index 3b263436720f..f82cda88757e 100644 --- a/.github/instructions/query-pack-change-notes.instructions.md +++ b/.github/instructions/query-pack-change-notes.instructions.md @@ -4,7 +4,7 @@ applyTo: "*/ql/src/change-notes/*.md" # Validation guide for query-pack change notes -When performing a code review, ensure that the Markdown change-notes in the pull request meet the following standards: +When reviewing change notes in a pull request, ensure that they meet the following standards. Suggest changes if necessary. ## File name The file name must match this pattern: `YYYY-MM-DD-description.md` From 5ba3b20f7f26cfb4d93614f2271453219eb9c5ae Mon Sep 17 00:00:00 2001 From: Mario Campos Date: Thu, 23 Oct 2025 15:36:36 +0000 Subject: [PATCH 5/5] Unify and expand change-note guidance Move and consolidate change-note validation guidance into docs/change-notes.md, removing the separate query- and library-pack instruction files. Add a generic .github/instructions/change-notes.instructions.md (applyTo: "**/change-notes/*.md") that tells reviewers to ensure change notes follow the docs and to leave clear review comments and code suggestions when they do not. --- .../instructions/change-notes.instructions.md | 8 + .../library-pack-change-notes.instructions.md | 105 ------ .../query-pack-change-notes.instructions.md | 105 ------ docs/change-notes.md | 336 +++++++++++++++--- 4 files changed, 293 insertions(+), 261 deletions(-) create mode 100644 .github/instructions/change-notes.instructions.md delete mode 100644 .github/instructions/library-pack-change-notes.instructions.md delete mode 100644 .github/instructions/query-pack-change-notes.instructions.md diff --git a/.github/instructions/change-notes.instructions.md b/.github/instructions/change-notes.instructions.md new file mode 100644 index 000000000000..7041224967a8 --- /dev/null +++ b/.github/instructions/change-notes.instructions.md @@ -0,0 +1,8 @@ +--- +applyTo: "**/change-notes/*.md" +--- + +Ensure that change notes follow the project's guidelines as described in `docs/change-notes.md`. If the change note does not satisfy the aforementioned guidelines: + +1. Leave a review comment that clearly explains the problem with the change note and how it can be improved. +2. Offer a code suggestion that would fix the problem. \ No newline at end of file diff --git a/.github/instructions/library-pack-change-notes.instructions.md b/.github/instructions/library-pack-change-notes.instructions.md deleted file mode 100644 index 1df88fff3537..000000000000 --- a/.github/instructions/library-pack-change-notes.instructions.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -applyTo: "*/ql/lib/change-notes/*.md,shared/*/change-notes/*.md" ---- - -# Validation guide for library-pack change notes - -When reviewing change notes in a pull request, ensure that they meet the following standards. Suggest changes if necessary. - -## File name -The file name must match this pattern: `YYYY-MM-DD-description.md` -- `YYYY-MM-DD` should refer to the year, month, and day, respectively, of the change; -- `description` should refer to a short alphanumerical text, separated by hyphens, that describes the change-note; -- The extension should be ".md". - -### Examples -#### Valid - -- 2020-10-12-new-client-library.md -- 2025-01-01-refactored-database-logic.md -- 2022-12-25-removed-log4j.md - -#### Invalid - -- 3000-60-32-invalid-date.md -- no-date-in-file-name.md -- 2019-01-01 file name contains spaces.md - -## Frontmatter -The file must begin with YAML frontmatter. Valid YAML frontmatter properties include: - -- `category` - - Required - - This is a string that identifies one of a fixed set of categories that the change falls into. -- `tags` - - Optional - - A list of string tags. - - -### Categories -| Category | Description | -|------------------|-------------| -| `breaking` | Any breaking change to the library pack, the most common of which is the deletion of an existing API. | -| `deprecated` | An existing API has been marked as deprecated. | -| `feature` | A new library API has been added. | -| `majorAnalysis` | An API has changed in a way that may affect the results produced by a query that consumes the API. | -| `minorAnalysis` | An API has changed in a way that may affect the results produced by a query that consumes the API, but only in scenarios that affect relatively few users. | -| `fix` | An API has been fixed in a way that is not likely to affect the results produced by a query that consumes the API. | - -### Examples -#### Valid - -```yaml ---- -category: feature ---- -``` - -```yaml ---- -category: majorAnalysis -tags: cpp ---- -``` - -#### Invalid - -##### Missing `category` property - -```yaml ---- -tags: cpp ---- -``` - -##### Invalid category `bug`; use `fix` instead - -```yaml ---- -category: bug ---- -``` - -## Description -The content after the YAML frontmatter must be an American-English description of the change in one or more unordered Markdown list entries. - -### Examples - -#### Valid - -```markdown -* Added support for the Nim programming language. -``` - -#### Invalid - -##### Change description is not in a bullet-list entry -```markdown -Added support for the Nim programming language. -``` - -##### No headers; only list entries -```markdown -# Fixes -* Fixed C++ source parsing to handle comma operator. -``` diff --git a/.github/instructions/query-pack-change-notes.instructions.md b/.github/instructions/query-pack-change-notes.instructions.md deleted file mode 100644 index f82cda88757e..000000000000 --- a/.github/instructions/query-pack-change-notes.instructions.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -applyTo: "*/ql/src/change-notes/*.md" ---- - -# Validation guide for query-pack change notes - -When reviewing change notes in a pull request, ensure that they meet the following standards. Suggest changes if necessary. - -## File name -The file name must match this pattern: `YYYY-MM-DD-description.md` -- `YYYY-MM-DD` should refer to the year, month, and day, respectively, of the change; -- `description` should refer to a short alphanumerical text, separated by hyphens, that describes the change-note; -- The extension should be ".md". - -### Examples -#### Valid - -- 2020-10-12-new-client-library.md -- 2025-01-01-refactored-database-logic.md -- 2022-12-25-removed-log4j.md - -#### Invalid - -- 3000-60-32-invalid-date.md -- no-date-in-file-name.md -- 2019-01-01 file name contains spaces.md - -## Frontmatter -The file must begin with YAML frontmatter. Valid YAML frontmatter properties include: - -- `category` - - Required - - This is a string that identifies one of a fixed set of categories that the change falls into. -- `tags` - - Optional - - A list of string tags. - -### Categories -| Category | Description | -|------------------|-------------| -| `breaking` | Any breaking change to the query pack, the most common of which is the deletion of an existing query. | -| `deprecated` | An existing query has been marked as `deprecated`. | -| `newQuery` | A new query has been added. | -| `queryMetadata` | The metadata of a query has been changed (e.g., to increase or reduce the `@precision`). | -| `majorAnalysis` | The set of results produced by a query has changed (fewer false positives, more true positives, etc.) enough to be noticed by users of the query pack. | -| `minorAnalysis` | The set of results produced by a query has changed, but only in scenarios that affect relatively few users. | -| `fix` | A fix that does not change the results reported by a query (e.g., a performance fix). | - -### Examples -#### Valid - -```yaml ---- -category: newQuery ---- -``` - -```yaml ---- -category: majorAnalysis -tags: cpp ---- -``` - -#### Invalid - -##### Missing `category` property - -```yaml ---- -tags: cpp ---- -``` - -##### Invalid category `bug`; use `fix` instead - -```yaml ---- -category: bug ---- -``` - -## Description -The content after the YAML frontmatter must be an American-English description of the change in one or more unordered Markdown list entries. - -### Examples - -#### Valid - -```markdown -* Added support for the Nim programming language. -``` - -#### Invalid - -##### Change description is not in a bullet-list entry -```markdown -Added support for the Nim programming language. -``` - -##### No headers; only list entries -```markdown -# Fixes -* Fixed C++ source parsing to handle comma operator. -``` diff --git a/docs/change-notes.md b/docs/change-notes.md index 7bf33447f6ed..45e6f4f14a40 100644 --- a/docs/change-notes.md +++ b/docs/change-notes.md @@ -1,88 +1,322 @@ -# Adding change notes for query and library changes +# CodeQL pack change notes -Each CodeQL query pack or library pack has its own change log to track how that pack changes with each release. Any non-trivial, user-visible change to a query or library should add a change note to the affected pack. This document describes how to do that. +Each CodeQL query pack and library pack has a CHANGELOG.md file to track how that pack changes with each release. Any non-trivial, user-visible change to a query pack or library pack should include a corresponding change-note file. -## Creating a change note -To create a new change note for a pack, create a new markdown file in the `change-notes` directory of the pack (e.g., in `cpp/ql/src/change-notes` for the C++ standard query pack). The markdown file must be named `YYYY-MM-DD-id.md`, where `YYYY-MM-DD` is the date of the change, and `id` is a short string to help identify the change. For example, if you were adding a new integer overflow query to the C++ standard query pack, you might do so from a branch named `int-overflow-query`, with a change note file named `cpp/ql/src/change-notes/2021-12-14-int-overflow-query.md`. Here are a few example change note files: +## How change notes are used +### How change notes are combined to form the CHANGELOG.md file + +When a new release of a pack is published, the publishing process consolidates all of the change-note files from that pack's `change-notes` directory into the pack's `CHANGELOG.md` file. The consolidation process does the following: + +- Strips all frontmatter from each change note. +- Strips all leading and trailing blank lines from the description of each change note. +- Adds a newline at the end of the description of any change note that does not already end with a newline. +- Groups change notes by `category`. +- Adds a section to the CHANGELOG.md file for each `category` that contains at least one change note. The section consists of a section heading followed by the contents of each change note in that `category`. +- Deletes the individual change-note files. + +### How change notes affect the version of the pack + +When a new release of a pack is published, the pack's version number is advanced based on the categories of the changes in that version: +- If any change note has a SemVer effect of `major version bump`, then the version number's major component will be incremented (e.g., `1.4.5` -> `2.0.0`). +- Otherwise, if any change note has a SemVer effect of `minor version bump`, then the version number's minor component will be incremented (e.g., `1.4.5` -> `1.5.0`). +- Otherwise, the version number's patch component will be incremented (e.g., `1.4.5` -> `1.4.6`). +Thus, it is important to choose the correct category for each change note, so that users can rely on the pack's version number to indicate compatibility with previous versions of the pack. + +## Format of a change-note file +### File path + +The location of the change-note file depends on whether it is for a query pack or library pack: +- For a query pack, the change-note file must be placed in the `ql/src/change-notes` directory of the query pack. +- For a library pack, the change-note file must be placed in the `ql/lib/change-notes` directory of the library pack. + - NOTE: the `shared` library packs, which live in `/shared/`, do not follow the same structure as other library packs. For these packs, the change-note file must be placed in the `/shared//change-notes` directory. + +#### Examples +##### Valid file paths for query-pack change notes + +- actions/ql/src/change-notes +- cpp/ql/src/change-notes +- javascript/ql/src/change-notes +- ql/ql/src/change-notes + +##### Invalid file paths for query-pack change notes + +- actions/ql/SRC/change-notes +- cpp/ql/lib/change-notes +- javascript/ql/change-notes +- ql/ql/src/change-notes/released +- ql/ql/src/change notes/released + +##### Valid file paths for library-pack change notes + +- go/ql/lib/change-notes +- swift/ql/lib/change-notes +- csharp/ql/lib/change-notes + +##### Invalid file paths for library-pack change notes + +- go/ql/src/change-notes +- go/ql/LIB/change-notes +- swift/change-notes +- swift/ql/src/change-notes +- csharp/ql/src/change-notes +- csharp/ql/change-notes + +##### Valid file paths for `shared` library-pack change notes + +- shared/mad/change-notes + +##### Invalid file paths for `shared` library-pack change notes + +- shared/mad/ql/lib/change-notes +- shared/mad/lib/change-notes +- shared/mad/src/change-notes + +### File name + +The change-note file must be named `YYYY-MM-DD-id.md`, where `YYYY-MM-DD` is the date of the change and `id` is a short sequence of American-English words, separated by hyphens, that describes the change. + +#### Examples of file names +##### Valid file names + +- 2020-10-12-new-db-client-library.md +- 2025-01-01-refactored-shopping-cart-logic.md +- 2021-11-24-removed-log4j-library.md +- 2021-12-14-int-overflow-query.md + +##### Invalid file names + +- 3000-60-32-invalid-date.md +- no-date-in-file-name.md +- 2019-01-01 file name contains spaces.md +- 2022-05-05-wrong-file-extension.txt + +### Frontmatter + +The change-note file must begin with YAML frontmatter. Valid YAML properties include: + +- `category` + - Required + - A string that labels the kind of change. The `category` serves two purposes. First, when a new version of a CodeQL pack is released, its change notes will be grouped together by their `category` and combined to form the pack's CHANGELOG.md file. Second, the `category` also determines how this change will affect the semantic-version number of the pack's next release. + - The set of categories from which to select will depend on whether the change note is for a query pack or a library pack. See the next section, titled "Change categories", for the available categories for each type of pack. + +#### Change categories + +There is one set of available categories for query packs, and another set of available categories for library packs. Be sure to choose a category from the correct set. + +##### Query-pack change categories + +| Category | SemVer effect | Description | +|----------------|--------------------|-------------| +| breaking | major version bump | Any breaking change to the query pack, the most common of which is the deletion of an existing query. | +| deprecated | minor version bump | An existing query has been marked as `deprecated`. | +| newQuery | minor version bump | A new query has been added. | +| queryMetadata | minor version bump | The metadata of a query has been changed (e.g., to increase or reduce the `@precision`). | +| majorAnalysis | minor version bump | The set of results produced by a query has changed (fewer false positives, more true positives, etc.) enough to be noticed by users of the query pack. | +| minorAnalysis | patch version bump | The set of results produced by a query has changed, but only in scenarios that affect relatively few users. | +| fix | patch version bump | A fix that does not change the results reported by a query (e.g., a performance fix). | + +##### Library-pack change categories + +| Category | SemVer effect | Description | +|----------------|--------------------|-------------| +| breaking | major version bump | Any breaking change to the library pack, the most common of which is the deletion of an existing API. | +| deprecated | minor version bump | An existing API has been marked as `deprecated`. | +| feature | minor version bump | A new library API has been added. | +| majorAnalysis | minor version bump | An API has changed in a way that may affect the results produced by a query that consumes the API. | +| minorAnalysis | patch version bump | An API has changed in a way that may affect the results produced by a query that consumes the API, but only in scenarios that affect relatively few users. | +| fix | patch version bump | An API has been fixed in a way that is not likely to affect the results produced by a query that consumes the API. | + +#### Examples of frontmatter +##### Valid frontmatter for query-pack change notes ```yaml --- category: newQuery --- -* Added a new query, `cpp/integer-overflow`, to detect code that depends on the result of signed integer overflow. ``` ```yaml --- category: fix --- -* Fixed a performance issue where the `cpp/integer-overflow` query would time out on large databases. ``` +##### Invalid frontmatter for query-pack change notes + +This example is invalid because `feature` is not a valid category for query-pack change notes: + ```yaml --- -category: minorAnalysis +category: feature +--- +``` + +This example is invalid because it is missing the required `category` property: + +```yaml +--- +--- +``` + +This example is invalid because `bug` is not a valid category; use `fix` instead: + +```yaml +--- +category: bug +--- +``` + +##### Valid frontmatter for library-pack change notes + +```yaml +--- +category: feature --- -* Added taint flow model for `std::codecvt`. ``` ```yaml --- category: majorAnalysis --- -* Added taint flow model for `std::string`. ``` -### Metadata -The change note file requires some metadata at the beginning of the file. This metadata is later used to determine how to advance the version number of the pack next time it is published, and to group related change notes in the final changelog. The metadata is YAML, enclosed by a `---` line before and after. +##### Invalid frontmatter for library-pack change notes -The valid YAML properties in the metadata are: +This example is invalid because `newQuery` is not a valid category for library-pack change notes: -- `category` - Required. This is a string that identifies one of a fixed set of categories that the change falls into. In the full changelog for the pack, the change notes for a particular release will be grouped together by category. The category also determines how this change will affect the version number of the pack's next release. For more information on available categories, see the Change Categories section below. -- `tags` - Optional. A list of string tags. These are not currently used by the change note infrastructure, so just omit this property. +```yaml +--- +category: newQuery +--- +``` + +This example is invalid because `deprecated` is misspelled: + +```yaml +--- +category: deprected +--- +``` ### Description -After the `---` line following the metadata, the rest of the markdown file is the user-visible content of the change note. This should usually be a single markdown bullet list entry (starting with `*`), although it is acceptable to have multiple bullet entries in the same change note if there are multiple changes that are closely related and have the same category metadata. -For consistency, change notes should use American English. +After the YAML frontmatter, the rest of the Markdown file is the user-visible content of the change note. This should usually be a single unordered Markdown-list entry (starting with `*`). However, it is also acceptable for the change note to have multiple list entries if there are multiple changes that are closely related and have the same `category`. -## Change categories -Each change note must specify a `category` property in its metadata. This category servers two purposes: It determines how the change affects the version number of the next release of the pack, and it is used to group related changes in the final changelog. There is one set of available categories for query packs, and another set of available categories for library packs. +For consistency, change notes should be written in American English. -### Query pack change categories -| Category | SemVer effect | Description | -|----------------|--------------------|-------------| -| breaking | major version bump | Any breaking change to the query pack, the most common of which is the deletion of an existing query. | -| deprecated | minor version bump | An existing query has been marked as `deprecated`. | -| newQuery | minor version bump | A new query has been added. | -| queryMetadata | minor version bump | The metadata of a query has been changed (e.g., to increase or reduce the `@precision`). | -| majorAnalysis | minor version bump | The set of results produced by a query has changed (fewer false positives, more true positives, etc.) enough to be noticed by users of the query pack. | -| minorAnalysis | patch version bump | The set of results produced by a query has changed, but only in scenarios that affect relatively few users. | -| fix | patch version bump | A fix that does not change the results reported by a query (e.g., a performance fix). | +### Examples of change-note descriptions +#### Valid change-note descriptions -### Library pack change categories -| Category | SemVer effect | Description | -|----------------|--------------------|-------------| -| breaking | major version bump | Any breaking change to the library pack, the most common of which is the deletion of an existing API. | -| deprecated | minor version bump | An existing API has been marked as `deprecated`. | -| feature | minor version bump | A new library API has been added. | -| majorAnalysis | minor version bump | An API has changed in a way that may affect the results produced by a query that consumes the API. | -| minorAnalysis | patch version bump | An API has changed in a way that may affect the results produced by a query that consumes the API, but only in scenarios that affect relatively few users. | -| fix | patch version bump | An API has been fixed in a way that is not likely to affect the results produced by a query that consumes the API. | +```markdown +* Added support for the Nim programming language. +``` -## How the final changelog is created -When a new release of a pack is published, the publishing process consolidates all of the change note files from that pack's `change-notes` directory into the pack's `CHANGELOG.md` file. The consolidation process does the following: +```markdown +* Fixed `cpp` extractor to support the comma operator in all contexts. +``` -- Strips all metadata from each change note. -- Strips all leading and trailing blank lines from the description of each change note. -- Adds a newline at the end of the description of any change note that does not already end with a newline. -- Groups change notes by category. -- Adds a section to the changelog for each category that contains at least one change note. The section consists of a section heading followed by the contents of each change note in that category. -- Deletes the individual change note files. +```markdown +* Minimized memory consumption. +* Upgraded to new GC algorithm. +* Optimized performance of string handling functions. +``` -## How change notes affect the version of the pack -When a new release of a pack is published, the pack's version number is advanced based on the categories of the changes in that version: -- If any change note has a SemVer effect of `major version bump`, then the version number's major component will be incremented (e.g., `1.4.5` -> `2.0.0`). -- Otherwise, if any change note has a SemVer effect of `minor version bump`, then the version number's minor component will be incremented (e.g., `1.4.5` -> `1.5.0`). -- Otherwise, the version number's patch component will be incremented (e.g., `1.4.5` -> `1.4.6`). -Thus, it is important to choose the correct category for each change note, so that users can rely on the pack's version number to indicate compatibility with previous versions of the pack. +#### Invalid change-note descriptions + +This example is invalid because it is missing the leading `*` for the list entry: + +```markdown +Added support for the Nim programming language. +``` + +This example is invalid because it begins with a heading instead of a list entry: + +```markdown +# Fixes +* Fixed C++ source parsing to handle comma operator. +``` + +This example is invalid because it is written in British English; use "Minimize" instead of "Minimise": + +```markdown +* Minimise memory consumption. +``` + +## Examples of complete change notes +### Valid complete change notes for query packs + +```yaml +--- +category: newQuery +--- +* Added a new query, `cpp/integer-overflow`, to detect code that depends on the result of signed integer overflow. +``` + +```yaml +--- +category: majorAnalysis +--- +* Added taint flow model for `std::codecvt`. +* Changed QL classes to require explicit import statements. +``` + +### Invalid complete change notes for query packs + +This example is invalid because `feature` is not a valid category for query-pack change notes: + +```yaml +--- +category: feature +--- +* Optimized SQL query performance for large databases. +``` + +This example is invalid because the Markdown description does not begin with `*`: + +```yaml +--- +category: breaking +--- ++ Disabled `go/sql-injection` query by default due to high false positive rate. +- Removed `go/old-xml-library` query. +``` + +### Valid complete change notes for library packs + +```yaml +--- +category: fix +--- +* Fixed a performance issue where the `cpp/integer-overflow` query would time out on large databases. +``` + +```yaml +--- +category: majorAnalysis +--- +* Added taint flow model for `std::string`. +``` + +### Invalid complete change notes for library packs + +This example is invalid because it contains too many changes in one note and the changes are not closely related: + +```yaml +--- +category: breaking +--- +* Added support for analysing Ruby on Rails applications. +* Minimized memory consumption. +* Improved data flow analysis precision. +* Added more logging for debugging purposes. +* Optimized performance of string handling functions. +``` + +This example is invalid because `newQuery` is not a valid category for library-pack change notes: + +```yaml +--- +category: newQuery +--- +* Added a new query, `cpp/integer-overflow`, to detect code that depends on the result of signed integer overflow. +``` \ No newline at end of file