Release notes plan

[richlander]

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:

• Add Supported OS JSON files #9294
• Linux packages JSON format #9412
• Add releases-index json schema #9424
• Add release-specific release.json files #9427
• Update release-index.json schema #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. 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. 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.

[richlander]

@Falco20019 @martincostello @omajid @leecow @rbhanda @baronfel

[Falco20019]

You could have a separate repo on dotnet for the tooling. Would make sense also for the nuget package linking to it. Then you can release it as dotnet tool for easy usage as global tool (most propably what you suggested).

[Falco20019]

I just found a minor issue with https://github.com/dotnet/core/blob/main/release-notes/6.0/supported-os.json#L341

10-20h2-e-lts does not exist, only 10-20h2-e which is already correclty in unsupported-versions. If I don't forget it, I will do a PR.

[richlander]

I found that added a $schema node can be a breaking change.

I did the following (in order, going back a bit):

• Wrote tools to process the various JSON files in the repo.
• Wrote a tool to generate schema files.
• Ran the tools.
• Added [JsonUnmappedMemberHandling(JsonUnmappedMemberHandling.Disallow)] to the OM and re-ran the generation tool.
• Manually added a $schema node to some of the JSON files
• Time passed
• Re-ran the tools. They broke.
• Error: Unhandled exception. System.Text.Json.JsonException: The JSON property '$schema' could not be mapped to any .NET member contained in type 'DotnetRelease.OSPackagesOverview'.
• Commenting out the JsonUnmappedMemberHandling attribute on the root object in the OM solved the problem.

The long and short of it is the following:

• Adding a $schema node after the fact can break consumers, if they have their own custom OM.
• Adding a $schema node prevents the use of JsonUnmappedMemberHandling.Disallow on the root object.

If there is something I'm doing wrong, that would be good to know. I don't think this finding is a huge problem, but it should influence our use of the $schema node and how we construct the schema.

@Falco20019 @eiriktsarpalis

[Falco20019]

Interesting finding. I would assume that JsonUnmappedMemberHandling.Disallow should not check $schema as it's a well-known node. But maybe @eiriktsarpalis can give us more insights. Maybe theres another attribute for setting the schema?

[richlander]

My conclusion is that STJ has no allowance for schemas meaning that the schema node is just another node.

[eiriktsarpalis]

That's correct, $schema has no special meaning in the context of plain old JSON serialization. Either removing UnmappedMemberHandling or making sure that it is being mapped to a property should resolve this for you:

[JsonPropertyName("$schema")]
public Uri? Schema { get; init; }