.NET Core Release Data (releases.json) Redesign and v1 Deprecation Plan

[leecow]

.NET Core Release Data (releases.json) Redesign and Deprecation

The releases.json and releases.csv files began life as helper tools for some of our internal release work, some experimentation and to possibly be useful to the community. It has been great to learn the files are indeed in use and many folks depend on them as a trigger for a number of activities.

• release-notes/releases.json
• release-notes/releases.csv

A discussion topic is available to share thoughts and see what others are thinking at dotnet/core#1986

Between the usages which we have become aware and in considering further activities that could be enabled to reason about things such as checking .NET Core version availability and support status, it became clear the current format is inadequate.

An updated format has been designed and tested which will replace the current files. The timeline below describes the path to obsoleting the current files.

The Plan

Date	Action
Oct 2018	Notify the community of the coming change
Oct 2018	Release the new json format into dotnet/core
Oct 2018 - Feb 2019	Maintain the old json and csv files
Feb 2019	Reminder announcement that old format file is coming soon
Dec 2019 (was Mar)	Old json and csv files are obsoleted and removed from dotnet/core

Breaking change

If you are currently utilizing the old version json or csv, you will need to update the relevant code to work with the new format. If you are just getting started with consuming this data, use the new version.

The Format

Below are fragments of the files from our most recent .NET Core release.

release-index.json

This file consists of a top level array with data on the latest release versions and a property for locating the more detailed channel-specific releases.json. This file is found in dotnet/core/release-notes

releases-index.json

{
    "releases-index": [
        {
            "channel-version": "2.1",
            "latest-release": "2.1.5",
            "latest-release-date":"2018-10-02",
            "product": ".NET Core",
            "support-phase": "lts",
            "eol-date": "",
            "releases.json": "https://github.com/dotnet/core/blob/master/release-notes/2.1/releases.json",
        },
        ...
}

releases.json

This file provides detailed data for each release. A copy of this file will be found in each versioned directories under dotnet/core/release-notes. For example dotnet/core/release-notes/2.1

releases.json

{
    "channel-version": "2.1",
    "latest-release": "2.1.5",
    "latest-release-date":"2018-10-12",
    "support-phase": "lts",
    "eol-date": "",
    "lifecycle-policy": "https://www.microsoft.com/net/support/policy",
    "releases":
    [
        {
            "release-date":  "2018-10-02",
            "release-version":  "2.1.5",
            "security":  false,
            "release-notes":  "https://github.com/dotnet/core/blob/master/release-notes/2.1/2.1.5/2.1.5.md",
            "runtime":  
            {
                "version":  "2.1.5",
                "version-display":  "2.1.5",
                "vs-version":  "15.8.6",
                "files":  
                [
                    {
                        "name": "dotnet-runtime-linux-arm.tar.gz",
                        "url": "https://download.visualstudio.microsoft.com/download/pr/4d555219-1f04-47c6-90e5-8b3ff8989b9c/0798763e6e4b98a62846116f997d046e/dotnet-runtime-2.1.5-linux-arm.tar.gz",
                        "hash": "89a77a07065ea24e7198c77a233b9ce5c6cf51b1deb2ef55c88f0adbb2ecd9db1ba4e7d55eec2ef7139c47f91346fed360161a5bb6e3a7ccfc4559bcde286364"
                    },
                    ...
                ]
            }
            "sdk":  
            {
                "version":  "2.1.403",
                "version-display":  "2.1.403",
                "vs-version":  "15.8.6",
                "csharp-language":  "7.3",
                "fsharp-language":  "4.5",
                "files":  
                [...]
            }
        }
    ]
}