Changelog missing deprecations and renames

[alanhajo-ui]

Hi,

We’ve now run into multiple cases where deprecations or API renames were not mentioned in the changelog. Each time, we missed the change during upgrades and it caused breakages on our side.

Right now, the changelog is not reliable for catching these kinds of changes. We scan it as part of our upgrade process, so if something is not listed there, we assume it is safe.

We would appreciate if you can start including:

• Deprecations
• Renames
• Any change that requires code updates, even if considered minor

Without that, upgrades become guesswork and create unnecessary regressions. LLMs struggle to scan as well if the codebase is huge.

Thanks.

[snowystinger]

Thanks for the issue, sorry to hear there have been problems upgrading. It's definitely never our intent to do that and we do go to great lengths to ensure backwards compatibility. Could you provide some specific examples? That would be helpful to us in classifying the issues.

We have marked various props and APIs as deprecated, but those should all still work, we have no plans as of now to remove them, and should we consider it, we will do announcements well ahead of time.

The only renames I'm aware of were our previous use of the UNSTABLE prefix on a prop. We know that caused some issues and have taken steps to fix that including keeping the old prop name around.

Thanks for understanding and look forward to hearing from you.

[kevinolsson]

Adding a concrete data point to back this up — we maintain a React component library built on top of react-aria-components, and the 1.14.0 → 1.17.0 upgrade required three separate PRs to address undocumented deprecations and renames.

Change 1: ListLayout sizing prop renames (rowHeight → rowSize, estimatedRowHeight → estimatedRowSize, headingHeight → headingSize, loaderHeight → loaderSize)

In 1.14.0, ListLayoutOptions only had the *Height props. In 1.17.0 (via react-stately 3.46.0), the new *Size props were introduced and the old ones marked @deprecated. We used these in internal constants and got a wave of TS deprecation errors with no changelog entry to explain why. Not in the 1.15.0, 1.16.0, or 1.17.0 changelogs.

Change 2: ComboBox selectedKey/onSelectionChange → value/onChange

In 1.14.0, selectedKey/defaultSelectedKey/onSelectionChange were the entire single-selection API for ComboBoxProps. In 1.17.0 (react-stately 3.46.0), a new ValueBase-based value/defaultValue/onChange API was added and the old props deprecated. This was not announced in any changelog between 1.14.0 and 1.17.0. Because our Search component wrapper had Omit<..., value> in its type, the new API caused a TypeScript error — we had no way to anticipate this from the changelog.

Change 3: UNSTABLE_portalContainer deprecated (Modal, Popover, Tooltip)

This one predates 1.14.0 so it is not a new 1.17.0 change, but we only surfaced the deprecation to our consumers as part of this upgrade cycle. No changelog entries across any of the three patch releases.

All three of these required us to update internal code and documentation, and we only caught them by diffing type files — not from changelogs. We scan the changelog as part of our upgrade process precisely to avoid this, so silent deprecations and renames that only appear in the .d.ts diff create real upgrade risk.

For what it is worth, none of these removed the old APIs — they are still present and functional — so we understand this is not a strict semver break. But deprecations that trigger TypeScript errors (depending on @typescript-eslint/no-deprecated or similar lint rules) do require code changes on upgrade, and those should be announced.

[snowystinger]

Thanks for the examples. So just to be clear, "Renames", is no longer an issue since they all have still working deprecated props. It's just the deprecations themselves.

I am happy to consider putting them in the release notes, hopefully in an automated way, and will bring it up with the team. However, I want to make sure we are solving your problems. Two things I'm still a little confused by.

• why isn't no-deprecated enough?
• are you pinning or using a range dependency on RAC?

What I mean more concretely.

If you are using "no-deprecated", shouldn't that appear when you do the upgrade? Which would amount to the same thing as it being in the release notes? I'm not understanding the difference or why you were only able to catch them by diffing type files instead of seeing all of them through that rule.

I can see Omit being an issue, I'm not sure what to do about that since some of these types can be very large. Otherwise I'd suggest using Pick instead. However, if you're specifying a range dependency on us, which makes the most sense if you're also a library, then this could happen regardless. You'd be better off using Pick for exactly what you allow through. I'm not sure how our release notes including this information would fix this problem.