dotnet / dotnet/core

Release notes plan

Open
#9,431 7 comments 0 reactions 0 assignees View on GitHub
area-release-notes
Dominant language
PowerShell
Stars
22k
Forks
4.9k
Avg merge
5d 5h
Merged PRs (30d)
29

Description

I'm working on updating our approach to release notes, in particular standardizing on JSON (as the primary format) and providing nice reading experiences with generated markdown (that are easy to adapt).

Relevant PRs and issues:

- https://github.com/dotnet/core/pull/9294
- https://github.com/dotnet/core/pull/9412
- https://github.com/dotnet/core/pull/9424
- https://github.com/dotnet/core/pull/9427
- https://github.com/dotnet/core/pull/9428

The process of writing a few JSON and markdown processing/generating tools has helped to inform the plan.

The fundamental question is determining which files are the source for others which are generated. This is obvious for JSON -> markdown generation but less obvious for JSON -> JSON generation.

More broadly, we want to ensure that some files are r/w and others are r/o and that the the r/o files ideally have just one source of data.

This plan isn't very novel. The intent is to document the plan and set expectations.

## Details

Our initial efforts with JSON release notes started with [`releases.json`](https://github.com/dotnet/core/blob/main/release-notes/1.0/releases.json). It's been our workhorse format for a decade now. There is a lot of value to "all release notes for a major release in a single file" as a model. It is also ideal as a source for content generation. We should continue with `releases.json` as our primary r/w file, using it to generate the other release-specific files.

- `releases.json` -- source
- `release-index.json` -- generated
- `patch-releases-index.json` -- generated
- `release.json` -- generated
- `supported-os.json` -- source
- `os-packages.json` -- source

This means that we'll transition to treating the generated files as r/o and not accept PRs for them (other than via re-running the content generation tool).

There is still a plan to add a `cves.json` file. I haven't done enough thinking on that yet. I'll get to that after implementing this plan.

I've been developing some tools for this project. They are currently in a personal repo at [richlander/distroessed](https://github.com/richlander/distroessed). We should decide where they should go. In theory, the dotnet/core repo is the best place for them. However, I'd like to actually do releases of the tools to make them easy to use. I'd prefer that releases on the dotnet/core repo were dedicated to actual .NET releases. I'm not sure which repo would be a better home.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.