Open richlander opened 2 months ago
@Falco20019 @martincostello @omajid @leecow @rbhanda @baronfel
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).
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.
I found that added a $schema
node can be a breaking change.
I did the following (in order, going back a bit):
[JsonUnmappedMemberHandling(JsonUnmappedMemberHandling.Disallow)]
to the OM and re-ran the generation tool.$schema
node to some of the JSON filesUnhandled exception. System.Text.Json.JsonException: The JSON property '$schema' could not be mapped to any .NET member contained in type 'DotnetRelease.OSPackagesOverview'.
JsonUnmappedMemberHandling
attribute on the root object in the OM solved the problem.The long and short of it is the following:
$schema
node after the fact can break consumers, if they have their own custom OM.$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
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?
My conclusion is that STJ has no allowance for schemas meaning that the schema node is just another node.
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; }
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:
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 withreleases.json
as our primary r/w file, using it to generate the other release-specific files.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.