Skip to content

Commit 489d5cd

Browse files
richlanderrichlander
committed
Add formats description
1 parent 827b472 commit 489d5cd

File tree

4 files changed

+419
-1
lines changed

4 files changed

+419
-1
lines changed

‎release-notes/formats.md

+95
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# Release note Formats
2+
3+
Release notes are available in a combination of markdown and JSON formats. The intent is to make all release notes available in markdown and also in JSON if there is a scenario that requires structured data. This content is [licensed](./license-information.md) for broad use.
4+
5+
Our approach has evolved over time. The following descripions are for our latest practices.
6+
7+
## Monthly patch release notes (markdown)
8+
9+
We typically release an update each month. These often include security fixes for vulberabilities (AKA CVEs) disclosed on the same day.
10+
11+
Example: [8.0.1](8.0/8.0.1/8.0.1.md)
12+
13+
These markdown files include the following information:
14+
15+
- Links to binaries
16+
- Notable changes, including CVEs
17+
- Compatibility information
18+
- Updates packages
19+
20+
## Monthly preview release notes (markdown)
21+
22+
We typically release a preview for the next major version each month. These are much the same as the monthly patches, however, will not include CVE information until the new major release is supported (starting with RC1).
23+
24+
Example: [.NET 9 Preview 6](./9.0/preview/preview6/README.md)
25+
26+
These markdown files are primarily composed of dense feature descriptions. This content is used as source material for [What's New](https://learn.microsoft.com/dotnet/core/whats-new/dotnet-9/overview) pages in official Microsoft docs, which are [often updated](https://github.com/dotnet/docs/pulls?q=is%3Apr+What%27s+New) on the same day as a preview release.
27+
28+
Preview release notes are always in a `preview` folder. This approach was adopted so that preview releases do distract from stable releases once preview releases are no longer relevant.
29+
30+
## Releases Index (json)
31+
32+
The `releases-index.json` file is the entrypoint into all other JSON files. This file is relatively small, about a dozen lines per major version. The file includes support phase, latest version, and whether the latest version included CVE fixes.
33+
34+
- File: [`releases-index.json`](./releases-index.json)
35+
- Schema: [`dotnet-releases-index.json`](https://json.schemastore.org/dotnet-releases-index.json)
36+
37+
The following example demonstrates a version object from the file.
38+
39+
```json
40+
{
41+
"channel-version": "8.0",
42+
"latest-release": "8.0.7",
43+
"latest-release-date": "2024-07-09",
44+
"security": true,
45+
"latest-runtime": "8.0.7",
46+
"latest-sdk": "8.0.303",
47+
"product": ".NET",
48+
"support-phase": "active",
49+
"eol-date": "2026-11-10",
50+
"release-type": "lts",
51+
"releases.json": "https://dotnetcli.blob.core.windows.net/dotnet/release-metadata/8.0/releases.json",
52+
"supported-os.json": "https://dotnetcli.blob.core.windows.net/dotnet/release-metadata/8.0/supported-os.json"
53+
}
54+
```
55+
56+
Each version object includes links to more detailed release-specific information.
57+
58+
The links are to a blob storage location, not to GitHub. We chose the blog storage links as the default because we knew some users were using the JSON files from within Azure and we also better understood the reliability characteristics of Azure.
59+
60+
`releases-index.json` and all the files it references are stored in blob storage and in GitHub. It is straightforward to programmatically transform the [blob storage links](https://dotnetcli.blob.core.windows.net/dotnet/release-metadata/releases-index.json) to [`raw` GitHub links](https://raw.githubusercontent.com/dotnet/core/main/release-notes/releases-index.json) should that be desired.
61+
62+
## Releases (json)
63+
64+
The `releases.json` file contains expansive release information for the life of a major release. It includes much the same information as the Monthly and preview markdown release notes.
65+
66+
Examples:
67+
68+
- [8.0 `releases.json`](./8.0/releases.json)
69+
- [9.0 `releases.json`](./9.0/releases.json)
70+
71+
This files can grow to be quite large. We are considering producing release-specific versions of this file, for example for `8.0/8.0.1/release.json`.
72+
73+
## Supported OS (json and markdown)
74+
75+
Supported OS information is published for each release. This information indicates to users which OSes they can expect an app (or the .NET SDK) to run on for a given .NET version. It also indicates which OSes are supported and when they transitioned to EOL status.
76+
77+
Examples:
78+
79+
- [.NET 8 Supported OSes (json)](./8.0/supported-os.json)
80+
- [.NET 8 Supported OSes (markdown)](./8.0/supported-os.md)
81+
- [.NET 9 Supported OSes (json)](./9.0/supported-os.json)
82+
- [.NET 9 Supported OSes (markdown)](./9.0/supported-os.md)
83+
84+
Schema: [dotnet-support-matrix](./schema/dotnet-support-matrix.json)
85+
86+
## Linux packages (json and markdown)
87+
88+
Linux package information is published for each release. This information indicates which packages must be installed on a given distro for a .NET app (or the .NET SDK) to run. [.NET packages](../linux.md) are available for multiple distros, which automatically install all required packages
89+
90+
Examples:
91+
92+
- [.NET Linux packages (json)](9.0/linux-packages.json)
93+
- [.NET Linux packages (markdown)](9.0/linux-packages.md)
94+
95+
Schema: [dotnet-requires-packages](./schema/dotnet-required-packages.json)

‎release-notes/license-information.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# License information for release notes
22

3-
Release notes include detailed information that may be useful in other forums or mediums, such as blogs, courses, or videos. The release notes are in markdown format, enabling flexible re-use. Starting with .NET 9, you will find more detailed release notes.
3+
Release notes include detailed information that may be useful in other forums or mediums, such as blogs, courses, or videos. The release notes are in markdown and JSON formats.
44

55
The [dotnet/core](https://github.com/dotnet/core) repo uses the [MIT license](../LICENSE.TXT). You are free to use release note content under that license.
66

‎release-notes/schema/dotnet-required-packages.json

+164
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
{
2+
"type": [
3+
"object",
4+
"null"
5+
],
6+
"properties": {
7+
"ChannelVersion": {
8+
"type": "string"
9+
},
10+
"EolDate": {
11+
"type": "string",
12+
"format": "date"
13+
},
14+
"Packages": {
15+
"type": "array",
16+
"items": {
17+
"type": [
18+
"object",
19+
"null"
20+
],
21+
"properties": {
22+
"Id": {
23+
"type": "string"
24+
},
25+
"Name": {
26+
"type": "string"
27+
},
28+
"References": {
29+
"type": [
30+
"array",
31+
"null"
32+
],
33+
"items": {
34+
"type": [
35+
"string",
36+
"null"
37+
]
38+
}
39+
},
40+
"Required": {
41+
"type": [
42+
"array",
43+
"null"
44+
],
45+
"items": {
46+
"type": [
47+
"string",
48+
"null"
49+
]
50+
}
51+
}
52+
},
53+
"required": [
54+
"Id",
55+
"Name",
56+
"References",
57+
"Required"
58+
]
59+
}
60+
},
61+
"Distributions": {
62+
"type": "array",
63+
"items": {
64+
"type": [
65+
"object",
66+
"null"
67+
],
68+
"properties": {
69+
"Name": {
70+
"type": "string"
71+
},
72+
"InstallCommands": {
73+
"type": [
74+
"array",
75+
"null"
76+
],
77+
"items": {
78+
"type": [
79+
"object",
80+
"null"
81+
],
82+
"properties": {
83+
"RunUnderSudo": {
84+
"type": "boolean"
85+
},
86+
"CommandRoot": {
87+
"type": "string"
88+
},
89+
"CommandParts": {
90+
"type": "array",
91+
"items": {
92+
"type": [
93+
"string",
94+
"null"
95+
]
96+
}
97+
}
98+
},
99+
"required": [
100+
"RunUnderSudo",
101+
"CommandRoot",
102+
"CommandParts"
103+
]
104+
}
105+
},
106+
"Releases": {
107+
"type": "array",
108+
"items": {
109+
"type": [
110+
"object",
111+
"null"
112+
],
113+
"properties": {
114+
"Name": {
115+
"type": "string"
116+
},
117+
"Release": {
118+
"type": "string"
119+
},
120+
"Packages": {
121+
"type": "array",
122+
"items": {
123+
"type": [
124+
"object",
125+
"null"
126+
],
127+
"properties": {
128+
"Id": {
129+
"type": "string"
130+
},
131+
"Name": {
132+
"type": "string"
133+
}
134+
},
135+
"required": [
136+
"Id",
137+
"Name"
138+
]
139+
}
140+
}
141+
},
142+
"required": [
143+
"Name",
144+
"Release",
145+
"Packages"
146+
]
147+
}
148+
}
149+
},
150+
"required": [
151+
"Name",
152+
"InstallCommands",
153+
"Releases"
154+
]
155+
}
156+
}
157+
},
158+
"required": [
159+
"ChannelVersion",
160+
"EolDate",
161+
"Packages",
162+
"Distributions"
163+
]
164+
}

0 commit comments

Comments
 (0)