Open glasser opened 2 years ago
This is a great idea. We can wrap it all up into an "Upgrade Notes" section.
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?
I think Upgrade Notes would be a new overall section that includes:
Suggestion
🔍 Search Terms
blog announcing release notes announcement downlevel-dts breaking changes
✅ Viability Checklist
My suggestion meets these guidelines:
⭐ 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.