Plan an upgrade

July 31, 2026 ยท View on GitHub

import {useState} from 'react'; import Link from '@docusaurus/Link'; import upgradeData from './boundaries.json';

export function UpgradePathChooser() { const versions = [ upgradeData.boundaries[0].from, ...upgradeData.boundaries.map((boundary) => boundary.to), ]; const latestStable = versions[versions.length - 1]; const [source, setSource] = useState('2.14.1'); const [target, setTarget] = useState(latestStable); const sourceIndex = versions.indexOf(source); const targetIndex = versions.indexOf(target); const path = sourceIndex < targetIndex ? upgradeData.boundaries.slice(sourceIndex, targetIndex) : [];

return (

{' '}

{sourceIndex > targetIndex && (

Choose a target newer than the source. Downgrades need a separate compatibility review.

)} {sourceIndex === targetIndex && (

No compatibility boundaries lie between the selected versions.

)} {path.length > 0 && (
    {path.map((boundary) => ( <li key={${boundary.from}-${boundary.to}}> {boundary.from} to {boundary.to}: {boundary.title}
    {boundary.summary} ))}
)}
); }

Plan an upgrade

Orientation

Choose the package version in your project or lock file as the source and the version you intend to install as the target. Follow every boundary shown, in order. This is a compatibility path, not a list of every feature or fix.

3.0.8 is intentionally a boundary. It restored source compatibility and introduced Roslyn-versioned analyzer assets that are absent from 3.0.1; 3.0.10 then corrected fallback selection for older build hosts.

For Humanizer 4, continue with the 3.0.10 to Humanizer 4 migration guide.

Example

For an upgrade from 2.13.14 to 3.0.10, the chooser produces this illustrative ordered chain:

2.13.14 -> 2.14.1 -> 3.0.1 -> 3.0.8 -> 3.0.10

Complete one guide and commit its mechanical changes before starting the next. That keeps package, compiler, and behavioral failures attributable to one boundary.

Pitfall

Do not jump straight from a 2.x package to the latest package and then treat every compiler error as a namespace error. Humanizer 3 also removes APIs, changes generic enum signatures and formatter extensibility, changes package assets, and includes patch-line compatibility restorations.

Version notes

The supported source and target list follows the documentation manifest. 3.0.8 is selectable here because published package contents and tagged source show remediation distinct from both 3.0.1 and 3.0.10. It remains a separate compatibility boundary even though the releases share one major/minor line.