Skip to content

library-pack-change-notes.instructions.md

Latest commit

 

History

History
105 lines (79 loc) · 2.58 KB

library-pack-change-notes.instructions.md

File metadata and controls

105 lines (79 loc) · 2.58 KB
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

---
category: feature
---
---
category: majorAnalysis
tags: cpp
---

Invalid

Missing category property
---
tags: cpp
---
Invalid category bug; use fix instead
---
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

* Added support for the Nim programming language.

Invalid

Change description is not in a bullet-list entry
Added support for the Nim programming language.
No headers; only list entries
# Fixes
* Fixed C++ source parsing to handle comma operator.