Skip to content

index.mdx

Latest commit

 

History

History
123 lines (104 loc) · 3.92 KB

index.mdx

File metadata and controls

123 lines (104 loc) · 3.92 KB
Raw
id upgrading
title Plan an upgrade
sidebar_position 1
diataxis how-to
persona upgrading developer
example illustrative

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 (

Source version{' '} <select value={source} onChange={(event) => setSource(event.target.value)}> {versions.map((version) => ( {version} ))} {' '} Target version{' '} <select value={target} onChange={(event) => setTarget(event.target.value)}> {versions.map((version) => ( {version} ))}

{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.

Related guides and API