update-release-graph

name

update-release-graph

description

Update the HAL+JSON release information graph when new .NET releases ship. Regenerates index files across the version hierarchy (root → major → patch), timeline hierarchy (timeline → year → month), llms.json, and downloads using graph generator tools. USE FOR: adding a new patch release to the graph, adding a new major version, updating timeline entries after a release, refreshing the graph after source data changes. DO NOT USE FOR: supported-os.json changes (use update-supported-os skill), querying the graph (use dotnet-releases skill on release-index branch), editing generated graph files by hand (update source data and regenerate).

Update Release Graph

Regenerate the HAL+JSON information graph in release-notes/. The graph is a set of interconnected JSON files using HAL _links and _embedded properties. It is generated from source data — never hand-edit the output files.

Architecture

Source data (inputs — edit these)

File	Location	Purpose
releases.json	{ver}/releases.json	Legacy release list with all patches, SDKs, component versions, download URLs, hashes
release.json	{ver}/{patch}/release.json	Individual patch release data (subset of releases.json entry)
_manifest.json	{ver}/_manifest.json	Lifecycle data and reference links (GA date, EOL date, what's-new, compatibility)
_llms.json	_llms.json (root, optional)	Partial overrides merged into generated llms.json
cve.json	timeline/{year}/{month}/cve.json	CVE disclosure records

Generated graph (outputs — do not hand-edit)

release-notes/
├── index.json                          ← root: all major versions
├── llms.json                           ← AI entry point: latest patches per supported version
├── {ver}/
│   ├── index.json                      ← major: all patches for this version
│   ├── manifest.json                   ← reference hub: compatibility, OS support, what's-new
│   ├── sdk/
│   │   ├── index.json                  ← SDK version index
│   │   └── sdk-{band}.json            ← per-band SDK history
│   ├── downloads/
│   │   ├── index.json                  ← components + feature bands
│   │   ├── runtime.json                ← per-RID runtime downloads
│   │   ├── sdk.json                    ← per-RID SDK downloads
│   │   ├── sdk-{band}.json            ← per-RID band-specific SDK downloads
│   │   ├── aspnetcore.json             ← per-RID ASP.NET Core downloads
│   │   └── windowsdesktop.json         ← per-RID Windows Desktop downloads
│   └── {patch}/
│       └── index.json                  ← patch detail (immutable after creation)
└── timeline/
    ├── index.json                      ← timeline root: all years
    ├── {year}/
    │   ├── index.json                  ← year: all months with releases
    │   └── {month}/
    │       └── index.json              ← month: all patches released (immutable)

Graph generators

The release-notes tool includes four graph generation commands:

Command	Generates	From
generate version-index	Root index, major indexes, patch indexes, manifests, SDK indexes, downloads	releases.json, release.json, _manifest.json, cve.json
generate timeline-index	Timeline root, year indexes, month indexes	Same sources + release calendar
generate llms-index	llms.json	Same sources (supported versions only)
generate indexes	All of the above in one shot	All source data

All accept the same arguments:

release-notes generate <type> <input-dir> [output-dir] [--url-root <url>]

When to use

• A new .NET patch release ships (monthly servicing) — source data is updated, graph needs regenerating
• A new .NET major version is added — _manifest.json and initial releases.json are created
• CVE data changes — cve.json files are updated, graph needs refreshing
• A .NET version reaches end-of-life — _manifest.json is updated, graph needs regenerating
• Any source data file is modified and the graph should reflect the changes

Prerequisites

release-notes

The release-notes tool handles both graph generation and legacy file operations. The public dotnet-release tool is for navigating release data and CVEs. Packages are published to GitHub Packages.

dotnet tool install -g release-notes \
  --add-source https://nuget.pkg.github.com/richlander/index.json

# Verify — should show graph generation commands
release-notes --help

Note: GitHub Packages requires authentication even for public repositories. If you get a 401 error, configure credentials for the source:

dotnet nuget add source https://nuget.pkg.github.com/richlander/index.json \
  --name github-richlander \
  --username USERNAME \
  --password "$GITHUB_TOKEN" \
  --store-password-in-clear-text

markdownlint

npm install -g markdownlint-cli

Inputs

The user provides:

• What changed — new patch release, new major version, EOL update, CVE refresh, etc.
• Which source files were updated — releases.json, release.json, _manifest.json, etc.
• Optionally, a custom --url-root for link generation (defaults to the release-index branch URL)

Process — Regenerate after a new patch release

This is the most common operation. Source data (releases.json, release.json) has been updated with a new patch release.

1. Verify source data is ready

Confirm these files exist and are updated:

# The major version's releases.json must include the new patch
cat release-notes/{ver}/releases.json | python3 -c "
import sys, json
data = json.load(sys.stdin)
print(f\"Latest: {data['releases'][0]['release-version']} ({data['releases'][0]['release-date']})\")"

# The patch directory should exist with release.json
ls release-notes/{ver}/{patch}/
# Expected: release.json, {patch}.md

The _manifest.json should also be present for the major version:

cat release-notes/{ver}/_manifest.json | python3 -c "
import sys, json
data = json.load(sys.stdin)
print(f\"Version: {data['version']}, Phase: {data['support_phase']}, EOL: {data.get('eol_date', 'N/A')}\")"

2. Run the graph generators

The simplest approach is generate indexes which runs all three generators in sequence:

# Generate all graph files in one shot
release-notes generate indexes release-notes

Or run each generator individually (order matters: version-index → timeline-index → llms-index):

release-notes generate version-index release-notes
release-notes generate timeline-index release-notes
release-notes generate llms-index release-notes

Custom URL root (for PR review before merging to release-index):

release-notes generate indexes release-notes --url-root https://raw.githubusercontent.com/dotnet/core/<commit-sha>

Separate output directory (to inspect output without overwriting source):

release-notes generate indexes release-notes /tmp/graph-output

The default URL root is https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/.

3. Regenerate legacy files

# Regenerate releases-index.json from releases.json files
release-notes generate releases-index release-notes

# Regenerate releases.md
release-notes generate releases release-notes

4. Validate

# Verify release links and hashes (can take minutes — do not cancel)
release-notes verify releases release-notes
# Or for a specific version
release-notes verify releases {ver} release-notes
# Skip hash verification for faster iteration
release-notes verify releases release-notes --skip-hash

# Lint generated markdown
npx markdownlint --config .github/linters/.markdown-lint.yml release-notes/releases.md

Exit codes for verify:

• 0 — no issues
• 2 — issues found (report written to stdout as markdown)

5. Spot-check the graph

Verify key relationships are correct:

# Root index lists all versions
python3 -c "
import json
data = json.load(open('release-notes/index.json'))
for r in data['_embedded']['releases']:
    print(f\"{r['version']}: supported={r.get('supported', 'N/A')}\")"

# Major index has the new patch as latest
python3 -c "
import json
data = json.load(open('release-notes/{ver}/index.json'))
print(f\"Latest patch: {data['latest_patch']}\")
print(f\"First embedded: {data['_embedded']['patches'][0]['version']}\")"

# Month timeline includes the patch
python3 -c "
import json
data = json.load(open('release-notes/timeline/{year}/{month}/index.json'))
for ver, patch in data['_embedded']['patches'].items():
    print(f\"{ver}: {patch['version']}\")"

# llms.json is current
python3 -c "
import json
data = json.load(open('release-notes/llms.json'))
for ver, patch in data['_embedded']['patches'].items():
    print(f\"{ver}: {patch['version']} ({patch['date']})\")"

6. Commit and PR

git checkout -b update-release-graph-{date}
git add release-notes/
git commit -m "Update release graph — {summary}"
gh pr create --title "Update release graph — {summary}" --body "{description}"

Process — Add a new major version

When a new .NET major version is added (e.g. .NET 11.0):

1. Create source data files

Create the _manifest.json with lifecycle data and reference links:

# release-notes/{ver}/_manifest.json

{
  "kind": "manifest",
  "title": ".NET {ver} Manifest",
  "version": "{ver}",
  "label": ".NET {ver}",
  "target_framework": "net{ver_no_dot}",
  "release_type": "lts|sts",
  "support_phase": "preview|active",
  "ga_date": "20XX-11-XXTXX:XX:XXZ",
  "eol_date": "20XX-XX-XXTXX:XX:XXZ",
  "_links": {
    "downloads-html": { "href": "https://dotnet.microsoft.com/download/dotnet/{ver}", "title": "...", "type": "text/html" },
    "whats-new-html": { "href": "https://learn.microsoft.com/dotnet/core/whats-new/dotnet-{major}/overview", "title": "...", "type": "text/html" },
    "whats-new": { "href": "https://raw.githubusercontent.com/dotnet/docs/main/docs/core/whats-new/dotnet-{major}/overview.md", "title": "...", "type": "application/markdown" },
    "compatibility-html": { "href": "https://learn.microsoft.com/dotnet/core/compatibility/{ver}", "title": "...", "type": "text/html" }
  }
}

Create the initial releases.json with the first release entry.

Create the release.json in the patch directory.

2. Regenerate

Same as the patch release process — run release-notes generate indexes release-notes → legacy files.

3. Verify the new version appears

• In index.json root: new version in _embedded.releases
• In timeline/index.json: version added to the appropriate year's major_releases
• In llms.json: version in supported_major_releases and _embedded.patches

Process — Mark a version EOL

1. Update source data

Edit release-notes/{ver}/_manifest.json:

• Set "support_phase": "eol"
• Set "supported": false (if present)

2. Regenerate outputs

Run all generators. The tools will:

• Set supported: false in root index
• Remove from llms.json supported_major_releases and _embedded.patches
• Update support_phase in major index

Source data conventions

_manifest.json (partial manifest)

This is the authoritative source for lifecycle data. The generators merge it with computed data to produce the full manifest.json.

Required fields: kind, title, version, label, target_framework, release_type, support_phase, ga_date, eol_date.

The _links section contains reference links that are merged into the generated manifest. These are links that cannot be computed (what's-new pages, compatibility docs, release blog, etc.).

release.json (per-patch)

Contains the full release data for a single patch: component versions, download URLs, file hashes. This is a subset of the corresponding entry in releases.json.

The generators use release.json to:

• Build patch detail indexes with embedded runtime/SDK data
• Generate per-RID download files
• Compute SDK feature band information

Preview releases

Preview/RC releases are stored in a different directory structure:

• {ver}/preview/preview1/ for preview.1
• {ver}/preview/rc1/ for RC1

The generators automatically detect this from the version string (contains -preview. or -rc.).

After GA, the generators filter previews from _embedded.patches in the major index. RC releases are kept because they have go-live support.

Graph conventions

Convention	Rule
Properties	snake_case_lower
Link relations	kebab-case-lower
Dates	ISO 8601 with timezone: 2026-02-10T00:00:00+00:00
Default URL root	https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/
$schema	Injected by generators; points to schemas/v1/
kind	Discriminator: root, major, patch, month, year, timeline, llms, manifest, downloads

Mutability

Index Type	Mutable?	Notes
Root index	Yes	Updated when versions are added/removed
Major index	Yes	Updated monthly with new patches
Patch detail	No	Frozen after creation
Timeline root	Yes	Updated when new years are added
Year index	Yes	Updated monthly
Month index	No	Frozen after creation
llms.json	Yes	Updated with every release
manifest.json	Rarely	Generated from _manifest.json
Downloads files	Yes	Updated with new release download URLs

Immutable files use only prev-* links (no next). Mutable files use latest-* links.

Key facts

• The graph is fully generated — edit source data (releases.json, release.json, _manifest.json), then run the generators
• Never hand-edit generated files (index.json, manifest.json, llms.json, downloads files, timeline indexes)
• _manifest.json (with underscore prefix) is the source; manifest.json (without prefix) is the generated output
• Similarly, _llms.json is optional source overrides; llms.json is the generated output
• releases-index.json (legacy flat format) is generated by release-notes generate releases-index
• releases.md is generated by release-notes generate releases
• The generators are idempotent — running them on unchanged source data produces identical output
• When running individually, order matters: version-index → timeline-index → llms-index; generate indexes handles this automatically
• All _links.*.href values are absolute URLs; the base URL is controlled by --url-root
• _embedded.patches is an array (newest first) in major indexes; an object keyed by major version in month indexes
• CVE data in the graph comes from timeline/{year}/{month}/cve.json

Common mistakes

Mistake	Correction
Hand-editing index.json or other generated files	Edit source data and re-run the generators
Hand-editing manifest.json	Edit _manifest.json and re-run VersionIndex
Hand-editing releases-index.json	Run release-notes generate releases-index release-notes
Hand-editing releases.md	Run release-notes generate releases release-notes
Running generators in wrong order	Use generate indexes (handles order automatically) or run: version-index → timeline-index → llms-index
Missing _manifest.json for a version	The generators warn but fall back to releases.json; create _manifest.json for accurate lifecycle data
Missing release.json for a patch	Patch detail index will be incomplete; ensure every patch has a release.json
Editing source data without regenerating	Always run release-notes generate indexes release-notes after changing source files
Forgetting --url-root for PR review	Links will use the default release-index branch URL; pass --url-root with a commit SHA for verifiable links in PRs