Skip to content

Commit 1c2ee6e

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

File tree

1 file changed

+123
-0
lines changed

1 file changed

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

0 commit comments

Comments
 (0)