Publish a support matrix

How to do it

Users plan their upgrades around the matrix, and an unannounced drop breaks their builds. List each runtime version, such as Node.js 22 and 24 or Python 3.11 to 3.15. List each operating system for native code, and how long each major version of the library gets security fixes. Products for the EU market must state a support period, as Handle vulnerabilities for the whole support period says. Never list a runtime past its end of life, as Running software that is out of support says. Describe what each release contains, as Publish what is in each release says.

Examples

JavaScript example

import { readFileSync } from 'node:fs';

const documented = JSON.parse(readFileSync('support-matrix.json', 'utf8')).node.toSorted();
const tested = [...readFileSync('.github/workflows/test.yml', 'utf8').matchAll(/node:\s*\[([^\]]+)\]/g)][0][1].split(',').map(v => v.trim()).toSorted();
if (documented.join() !== tested.join()) { console.error(`Matrix ${documented} differs from CI ${tested}`); process.exit(1); }

Python example

import json, re, sys
from pathlib import Path

documented = sorted(json.loads(Path("support-matrix.json").read_text())["python"])
workflow = Path(".github/workflows/test.yml").read_text()
tested = sorted(v.strip().strip('"') for v in re.search(r"python:\s*\[([^\]]+)\]", workflow).group(1).split(","))
if documented != tested:
    sys.exit(f"Matrix {documented} differs from CI {tested}")

How to check

A script compares the runtime versions in the published matrix with the CI test matrix and fails on any difference. No listed runtime is past its end-of-life date.

Sources

• Node.js releases
• Status of Python versions

Related rules

• ENG-74 Test both versions during an upgrade in Engineering
• OSS-23 Fix a reported hole in private in Open source maintenance
• CMP-50 Handle vulnerabilities for the whole support period in Compliance and governance
• STK-15 Running software that is out of support in Software choices
• APS-75 Publish what is in each release in Application security