Process suggestion: describe breaking changes to .d.ts files in "Announcing TypeScript 4.x" blog posts

[glasser]

Suggestion

🔍 Search Terms

blog announcing release notes announcement downlevel-dts breaking changes

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

The TypeScript project's release announcement blog posts (like this one for 4.8) are excellently crafted documents. I look forward to reading each one. They teach me about new features with motivating examples, and describe breaking changes that I may have to deal with.

However, there's one class of changes that I can't easily learn about from these release posts (and I don't believe there's anywhere else that answers the same question). I don't know an easy way to answer the questions "If I upgrade to this version, build a library, and publish its .d.ts files, will my library's users also have to use this new version? Does this answer depend on whether I use new features or whether I set specific settings?

For example, in TS 4.7, using variance annotations would require consumers of .d.ts files to upgrade to TS 4.7; the upgrade isn't required if you don't use the feature.

On the other hand, I don't think TS 4.8 contains any syntax changes to generated .d.ts files.

In a sense, I'm looking for an easy way to learn about whether the release introduces any changes for which downlevel-dts might be helpful. I think this would go well in the announcement blog post, or somewhere else that's easy to find for each release.

📃 Motivating Example

Being able to tell the difference between features like variance annotations (which require consumers of .d.ts files to upgrade TS) and other features.

💻 Use Cases

Understanding when I upgrade TypeScript or use new features if I am also forcing consumers of my library to upgrade TypeScript.

[RyanCavanaugh]

This is a great idea. We can wrap it all up into an "Upgrade Notes" section.

[DanielRosenwasser]

I could see that. One thing we changed in 4.8 RC was "Breaking Changes" became something like "Correctness Improvements and Breaking Changes". Is "Upgrade Notes" just a rename of that, or is it a separate section?

[RyanCavanaugh]

I think Upgrade Notes would be a new overall section that includes:

• "Actual" breaks
• Correctness improvements
• Back-compat concerns (i.e. declaration emit compatibility and whether it requires an opt-in)