Skip to content

Commit 9f65419

Browse files
authored
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.
1 parent a0d2005 commit 9f65419

File tree

1 file changed

+116
-0
lines changed

1 file changed

+116
-0
lines changed
Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
---
2+
applyTo: >
3+
actions/ql/src/change-notes/*.md,
4+
cpp/ql/src/change-notes/*.md,
5+
csharp/ql/src/change-notes/*.md,
6+
go/ql/src/change-notes/*.md,
7+
java/ql/src/change-notes/*.md,
8+
javascript/ql/src/change-notes/*.md,
9+
python/ql/src/change-notes/*.md,
10+
ql/ql/src/change-notes/*.md,
11+
ruby/ql/src/change-notes/*.md,
12+
rust/ql/src/change-notes/*.md,
13+
swift/ql/src/change-notes/*.md
14+
---
15+
16+
# Validation guide for query-pack change notes
17+
18+
When performing a code review, ensure that the Markdown change-notes in the pull request meet the following standards:
19+
20+
## File name
21+
The file name must match this pattern: `YYYY-MM-DD-description.md`
22+
- `YYYY-MM-DD` should refer to the year, month, and day, respectively, of the change;
23+
- `description` should refer to a short alphanumerical text, separated by hyphens, that describes the change-note;
24+
- The extension should be ".md".
25+
26+
### Examples
27+
#### Valid
28+
29+
- 2020-10-12-new-client-library.md
30+
- 2025-01-01-refactored-database-logic.md
31+
- 2022-12-25-removed-log4j.md
32+
33+
#### Invalid
34+
35+
- 3000-60-32-invalid-date.md
36+
- no-date-in-file-name.md
37+
- 2019-01-01 file name contains spaces.md
38+
39+
## Frontmatter
40+
The file must begin with YAML frontmatter. Valid YAML frontmatter properties include:
41+
42+
- `category`
43+
- Required
44+
- This is a string that identifies one of a fixed set of categories that the change falls into.
45+
- `tags`
46+
- Optional
47+
- A list of string tags.
48+
49+
### Categories
50+
| Category | Description |
51+
|------------------|-------------|
52+
| `breaking` | Any breaking change to the query pack, the most common of which is the deletion of an existing query. |
53+
| `deprecated` | An existing query has been marked as `deprecated`. |
54+
| `newQuery` | A new query has been added. |
55+
| `queryMetadata` | The metadata of a query has been changed (e.g., to increase or reduce the `@precision`). |
56+
| `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. |
57+
| `minorAnalysis` | The set of results produced by a query has changed, but only in scenarios that affect relatively few users. |
58+
| `fix` | A fix that does not change the results reported by a query (e.g., a performance fix). |
59+
60+
### Examples
61+
#### Valid
62+
63+
```yaml
64+
---
65+
category: newQuery
66+
---
67+
```
68+
69+
```yaml
70+
---
71+
category: majorAnalysis
72+
tags: cpp
73+
---
74+
```
75+
76+
#### Invalid
77+
78+
##### Missing `category` property
79+
80+
```yaml
81+
---
82+
tags: cpp
83+
---
84+
```
85+
86+
##### Invalid category `bug`; use `fix` instead
87+
88+
```yaml
89+
---
90+
category: bug
91+
---
92+
```
93+
94+
## Description
95+
The content after the YAML frontmatter must be an American-English description of the change in one or more unordered Markdown list entries.
96+
97+
### Examples
98+
99+
#### Valid
100+
101+
```markdown
102+
* Added support for the Nim programming language.
103+
```
104+
105+
#### Invalid
106+
107+
##### Change description is not in a bullet-list entry
108+
```markdown
109+
Added support for the Nim programming language.
110+
```
111+
112+
##### No headers; only list entries
113+
```markdown
114+
# Fixes
115+
* Fixed C++ source parsing to handle comma operator.
116+
```

0 commit comments

Comments
 (0)