Update .NET Supported OS Matrix

Update Supported OS

Audit and update supported-os.json files in this repository. These files declare which operating system versions are supported for each .NET release. The corresponding supported-os.md files are generated from JSON — never hand-edit them.

When to use

• A new OS version is released (e.g. Ubuntu 26.04, Fedora 44, Alpine 3.23)
• An OS version reaches end-of-life and should be moved to unsupported
• Periodic audit to ensure the support matrix is current

Prerequisites

The following tools must be installed:

release-notes

The release-notes tool is used to verify and generate supported OS files. The public dotnet-release tool is now for browsing release data and CVEs. Packages are published to GitHub Packages.

# GitHub Packages requires authentication — use a GitHub token (PAT or GITHUB_TOKEN)
dotnet tool install -g release-notes \
  --add-source https://nuget.pkg.github.com/richlander/index.json

# Verify
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

In GitHub Actions, GITHUB_TOKEN is available automatically. For local use, create a personal access token with read:packages scope.

markdownlint

The markdownlint-cli tool is used to validate generated markdown. Install via npm:

npm install -g markdownlint-cli

# Verify
npx markdownlint --version

If npm is not available, install Node.js first (e.g. brew install node on macOS). This is a required step — do not skip linting.

Inputs

The user provides:

• Versions to audit — which .NET versions to check (e.g. "8.0+", "10.0 only"), defaults to all active versions
• Optionally, specific distros or OS versions to focus on

Process

1. Verify — check for issues (early out)

Run the verify command for each .NET version to audit:

release-notes verify supported-os <version> release-notes

Examples:

# Check 10.0 against local files
release-notes verify supported-os 10.0 release-notes

# Check against live data on GitHub (no local clone needed)
release-notes verify supported-os 10.0

Interpret the exit code:

• Exit code 0 — No issues found. Stop here — nothing to do.
• Exit code 2 — Issues found. The report is written to stdout as markdown. Proceed to step 2.

The report uses GitHub callout blocks to categorize issues:

See references/verify-output-example.md for example output.

If all versions return exit code 0, the matrix is current. Stop here.

2. Determine scope of changes

First, determine whether this .NET version is GA or pre-GA (preview/RC). Check releases-index.json for the support-phase field, or ask the user.

GA releases

• WARNING — Move to unsupported-versions.
• IMPORTANT — Add to supported-versions unless there's a known reason to exclude.
• CAUTION — Informational only, no changes needed.
• TIP — Usually intentional, skip unless the user says otherwise.

Pre-GA releases

Apply the preview release rules below. The support matrix should reflect what will be supported at GA, not what happens to be active today.

• WARNING — Remove from supported-versions entirely. Do not add to unsupported-versions (Rule 1). Exception: skip Windows versions covered by ESU — unless the ESU itself expires before GA (see Rule 1).
• IMPORTANT — Only add if the version's EOL date is after GA + 6 months (Rule 2).
• CAUTION — Check the EOL date against the GA date. If EOL is before GA, remove from supported-versions (Rule 1). If EOL is after GA but before GA + 6 months, remove as well (Rule 2). If EOL is after GA + 6 months, no action needed.
• TIP — Same as GA, skip unless the user says otherwise.
• Rule 3 check — Independently of the verify report, check for preview distros that should be added proactively.

Present findings to the user with recommendations before making changes.

3. Apply changes to supported-os.json

For each confirmed change, edit release-notes/<version>/supported-os.json:

• EOL versions (GA): Remove from supported-versions, add to unsupported-versions
• EOL versions (pre-GA): Remove from supported-versions only — do not add to unsupported-versions
• Add new versions: Insert into supported-versions (keep sorted, newest first)
• Always update last-updated: Set to today's date (format: YYYY-MM-DD) in every JSON file that is modified — this is required for every change, no matter how small
• Use the edit tool for surgical JSON changes
• Versions are strings, not numbers — "3.22" not 3.22

4. Regenerate markdown

After updating the JSON, regenerate the markdown file:

release-notes generate supported-os <version> release-notes

This overwrites supported-os.md with content derived from the updated JSON.

Important: Do not hand-edit supported-os.md. It is generated from JSON by the tool. If the markdown output needs to change, update the generator or its Markout template in dotnet-release instead.

5. Run markdownlint

Verify the generated markdown passes linting (see prerequisites):

npx markdownlint --config .github/linters/.markdown-lint.yml release-notes/<version>/supported-os.md

CI runs markdownlint via super-linter and will block the PR if linting fails. If linting fails on generated content, fix the generator or its Markout template in dotnet-release — do not patch the markdown by hand.

6. Cross-reference with os-packages.json

Check if any newly added distro versions need entries in os-packages.json. If so, inform the user to run the update-os-packages skill next.

7. Validate changes

1. Run verify again to confirm issues are resolved:

   release-notes verify supported-os <version> release-notes

   Remaining items are acceptable if they are:

   • TIP items (intentionally unsupported)
   • ESU-covered WARNING items (GA releases, or pre-GA where ESU outlasts GA)
   • IMPORTANT items for versions intentionally excluded by Rule 2 (pre-GA)
   • CAUTION items with EOL after the GA date (pre-GA) or any CAUTION items (GA)

2. Spot-check the generated markdown renders correctly.

8. Create PR

1. Create a branch:

   git checkout -b update-supported-os-<date>

2. Commit all changed files (supported-os.json and supported-os.md for each version):

   git add release-notes/*/supported-os.json release-notes/*/supported-os.md
   git commit -m "Update supported OS matrix — <summary of changes>"

3. Push and open a PR:

   gh pr create --title "Update supported OS matrix" --body "<description of changes>"

Preview release rules

.NET releases go through a preview period before GA (General Availability). During this period, special rules apply to limit documentation cruft at GA and prevent users from deploying to environments that will soon lose support.

Determining GA date

.NET releases always GA in November. The version number and GA year follow a predictable pattern:

• Even .NET versions (10, 12, 14, …) GA in odd years — LTS (Long Term Support)
• Odd .NET versions (9, 11, 13, …) GA in even years — STS (Standard Term Support)

For example: .NET 10 GAs November 2025, .NET 11 GAs November 2026, .NET 12 GAs November 2027.

To confirm, check releases-index.json for the release-date of the target version. If the GA date is not yet populated, use the November convention above.

Rule 1 — Remove versions that won't be supported at GA

While a .NET release is in preview, remove OS versions from supported-versions if they are already EOL or will reach EOL before the GA date. Do not add them to unsupported-versions — the unsupported list is for versions that were supported during a GA release and later went EOL. Since the .NET release hasn't shipped yet, there is no GA history to preserve.

This rule applies to both WARNING items (already EOL) and CAUTION items (approaching EOL with an EOL date before GA).

Windows ESU exception: Windows versions covered by Extended Security Updates (ESU) are not considered EOL while ESU is active. The verify tool flags these based on mainstream support dates, but ESU extends their lifecycle. However, check whether the ESU program itself expires before the GA date — if it does, the version should be removed.

Rationale: The unsupported-versions list exists as a historical record for users of a shipped release. During preview, no users depend on the support matrix, so versions that won't survive to GA should simply be removed to keep the document clean.