Definitelytyped: META - Updating minimum TypeScript version

When was unknown added? Go big or go home! All the any in DT is by far the largest source of "typescript shoulda caught it" bugs in these here parts.

When was unknown added?

3.0

ty. So, 99.9%!

I agree we should do this. Let's do this!

Please, could you instead increase it slowly over time? 2.1 one month, 2.2 the next, and so on?

Each version has some small breaking changes. It'll be easier to understand what troubles this brings by going slowly and methodically at first.

Projects in maintenance mode often don't have the bandwidth to overcome those breaking changes, especially if they're core to infrastructure.

Yes please, the node typings in particular have suffered from the lack of newer features and many ~hacks~ workarounds had to be used.

@JoshuaKGoldberg projects in maintenance mode are not likely to be upgrading versions of type definitions month after month, yeah?

@JoshuaKGoldberg do remember that upgrading DT does not remove the historic type definitions that have already been published to npm. @types historic versions live forever like Mumm-Ra.

You'll be able to depend upon those regardless of where DT goes versioning-wise.

Makes sense

Hi @RyanCavanaugh,
I support such idea 100%. TypeScript v2.0 is blocker for better type system for many packages including node.
I care about Transparency and predictability for community and business. There is questions:

• When do you think is good time change the minimum-supported TypeScript version? During release TS 3.7?
• Correct me if I wrong, but this looks like end of life for TypeScript versions before 2.8?
• Could we have schedule similar to Node.js? Such document will help dev teams push business to approve development resources for update.

Any reason why it's 2.8 and not a different version? (E.g. 3.0 for unknown.)

2.8 is when conditional types were introduced

Hugely in favor.

Please, while you're at it, consider setting up a (semi-)formal schedule so the community can count on the minimum version predictably increasing over time. Something like: "Every year in November, we plan to update the minimum typescript version to the release from 18 months prior. Please plan accordingly."

@donaldpipowitch
Of the pre-3.0 users, we saw a cluster of people still on 2.8. (And, of course, conditional types make 2.8 a popular target for DT types as @IllusionMH points out.)

We expect to revisit this issue periodically because we hope people continue to upgrade.

@galkin
Technically, old versions of Typescript are not serviced at all, and this change is the stop of service from Definitely Typed. And of course old versions of Typescript can continue to get the existing versions of DT packages. They just won't get updates.

However, that's just a technicality. It would be a good idea for us to produce a LTS-like schedule. We have not started on anything like that yet though. In this case the data were clear enough to make the post-hoc decision easy. I'm not sure yet how to predict a good date for future deprecations.

Re: the date: I have to update the DT infrastructure for 3.7 anyway, so it will happen on 3.7's release day as part of the release.

It would be a good idea for us to produce a LTS-like schedule.

Just wanted to echo I think this sort of schedule is a really solid idea.

@johnnyreilly we're looking around Microsoft for precedent. There's nothing quite like Definitely Typed though!

@RyanCavanaugh, any updates?

@galkin if you have a proposed deprecation schedule, please do post it to this thread so we can discuss.

@sandersn, here are my thoughts on this issue

• Do we need End-of-life (EOL) for TypeScript Version?
  Of course, yes. Support every created TypeScript version requires surplus resources.
• Why should we have EOL schedule?
  _The best practice is to just be upfront and clear with the state of your projects. If you’re no longer supporting a project, or you’re in the process of winding it down, make that painfully obvious to anybody that would stumble across your code_ (c) Jared Smith.
• What should be used as base for the schedule?
  Analytics? Every decision based on analytics is compromise. Every such decision is answer on question what part of community/business will we tease. WordPress has similar issue what minimal version of WP/PHP/MySQL they should support. It is dangerous way.
  Dependent tool schedule? Visual Code/Microsoft Azure/Angular/etc. Too many options and too easy start new holy war.
  TC39 Process? Good option, but TC39 doesn't and will not introduce EoL for any language feature.
  Node.js? Node.js is driver for JS community with release/EOL schedule. TypeScript uses Node.js. I see this as best base for the schedule.
• How create the schedule?
  Option 1. Associate TypeScript version with Node.js version and announce similar EOL. For example 2 year ago Node.js v8 started LTS and TypeScript v2.6 was released, so 2019.12.31 is EOL.
  Option 2 Node.js has 12 + 18 month policy before EOL. We can use the same approach, 2.5 years. It can be too long, but not less 2 years.
  Option 3 Make a meeting with decision makers and share with community result as it was

So my proposal looks something like that:

version | Released | End of Life in 2.5 years | End of Life in 2 years
-- | -- | -- | --
2.1 | December 2016 | June 2019 | December 2018
2.2 | February 2017 | August 2019 | February 2019
2.3 | April 2017 | September 2019 | April 2019
2.4 | June 2017 | November 2019 | June 2019
2.5 | August 2017 | January 2020 | August 2019
2.6 | October 2017 | March 2020 | October 2019
2.7 | January 2018 | July 2020 | January 2020
2.8 | March 2018 | August 2020 | February 2020
2.9 | May 2018 | October 2020 | April 2020
3 | July 2018 | December 2020 | June 2020
3.1 | September 2018 | March 2021 | August 2020
3.2 | November 2018 | May 2021 | October 2020
3.3 | January 2019 | July 2021 | December 2020
3.4 | March 2019 | August 2021 | February 2021
3.5 | May 2019 | October 2021 | April 2021
3.6 | August 2019 | January 2022 | July 2021
3.7 | November 2019 | May 2022 | October 2021

Wow, this is amazing! Thanks for the thought you put into this.

Couple of small points:

1. Definitely Typed and Typescript are different projects, although they should have the same EOL schedule.
2. What EOL means for DT is laid out above, but it's not so clear for TS. We have never created a patch version more than one minor version back to my knowledge. On the other side, we haven't recommended newer versions of TS to people except as general good practise, or for specific workarounds.
3. Since TS ships as part of Visual Studio, a paid product with support contracts, we may have to define a VS-specific extension to whatever open-source support period gets defined. This shouldn't affect the open source community though.

@DanielRosenwasser do you mind looking at this when you have time?

2.8 is now the new minimum. 2.0 - 2.7 will no longer be tested and the ts2.0 - ts2.7 tags will no longer be updated on existing @types/* packages. Pre-2.8 users who install @types/*@latest may get types that do not work for them.

I'm not going to close this issue since there's ongoing discussion (and it's a meta-issue besides?).

@sandersn does that mean that the check that usually verifies that a dependency has a greater or equal (eg. an arbitrary package (2.x with x > 1 referencing another package with x = 1) version is now disabled?

Asking because that's a major blocking of moving node typings forward.

@SimonSchick no, it is not disabled; it only applies for headers that require >=2.8.

In other words, you can't update @types/node to require 3.1 because there are lots of packages that specify 2.8 or 2.4 -- which is treated as 2.8. But you can definitely have @types/node require 2.8 now. That means you can use conditional types, and you can assume that 2.8+ semantics apply where they differ from old versions.

In fact, the default is 2.8, so not having a required version in the header at all is equivalent to requiring 2.8.

@sandersn, could we talk about new update of minimal version? I think it is a good time because 3.8 was released.

We've been discussing it internally and leaning toward supporting the node-style 30-month schedule. But I need to co-ordinate with the Typescript-VS integration team, who want to have a support timeline for new-TS-in-old-VS, so I haven't tried to restart the discussion yet; if we do end up with 30-months, the next deprecation will be in August, so we have a little time.

Update: I talked to the Typescript-Javascript team on VS and they have decided on either a 2-year or 2.5-year schedule. They are going to gather some usage data to help them decide between the two. I also got their scenario backward -- it's support for old-TS-in-new-VS.

Based on our usage data collected earlier [1], I prefer a 2-year window simply to reduce the maintenance burden. It also lets important packages start using new features 6 months sooner with no effort to update dependents. A short support window doesn't have practical downsides that I've seen so far.

However, node's schedule may cause people to expect a 2.5-year window instead. Are there other advantages of the longer window? Disadvantages that I'm missing?

[1]
Data reprinted from above:

• Telemetry indicates 99.9% of VS Code users are 3.0 or newer
• Telemetry indicates 97% of VS users are on 3.0 or newer
• 20% of DT packages have already opted in to 2.8 or newer

I favour a shorter window; both for reasons of reducing the maintenance burden and given the data you've uncovered @sandersn.

Thanks for the update!

Also for a shorter window.

A long window would only profit those that would only update part of their dependencies, but never typescript, and that should only be a very small group.
Most of the time, people either regularly update all their dependencies (including typescript), or none at all.
Or the other way round: Most developers that haven't bothered updating their TypeScript in two years probably don't care about fresh packages & fresh type definitions at all.
So this would probably hurt a lot less people than you might be suspecting - and it keeps the whole ecosystem from evolving.

TL;DR; @sandersn, what do you think about 18 months?

My thoughts:

I wrote

Option 2 Node.js has 12 + 18 month policy before EOL. We can use the same approach, 2.5 years. It can be too long, but not less 2 years.

but I can not remember why I thought 2 years is the right period of time. I can not logically substantiate this 2 years. Now, with a fresh mind, it seems to me that there should have been ..., but not less 18 months.

Every major version covered by the LTS plan will be actively maintained for a period of 12 months from the date it enters LTS coverage. Following those 12 months of active support, the major version will transition into "maintenance" mode for 18 additional months. Prior to Node.js 12 the active period was 18 months and the maintenance period 12 months. (c) Node.js Release Plan

Motivation: every TypeScipt version is released as rc/beta first. So every stable release has maintenance mode from the first day and 18 months is good enough.

That is logical. But if we use 18 months as the window, we would deprecate 3.1 in March 2020. Given that our telemetry showed a significant number of VS users still on 3.1, I don't think 3.1 should be deprecated yet.

However, it's possible that those numbers will have changed since the end of October. I'll find out what they currently are.

Usage numbers for 3.1 haven't gone down that much in VS since the end of October. Interestingly, 95% of the usage is concentrated in 3.9 - 3.4.

I think 3.1 is still used so much because VS will let you avoid updating typescript when downloading updates, but I'm not sure. Regardless, this behaviour is likely to continue in future versions of VS, plus other IDEs that don't update that often.

In summary, to support 98% of VS users, we need a 2-year window. To support 95%, we only need a 1-year window! But there's not much point in having anything in between.

I still support 2 years based on that data.

It looks to me like the discussion here has wound down. I'm going to go with a 2-year support window.

2.8 released on March 27, 2018, so I'm not going to remove support immediately. But I will do so in the next couple of weeks, and I'll update and close this issue when it's done.

I have a PR that adds documentation to the README at #42834.

I translated the documentation changes into Russian at #42881

Could somebody help with translation changes into:

• README.cn.md
• README.es.md
• README.ko.md

@kingwl @armanio123 @saschanaz are the most involved Typescripters that I know who are native speakers for those three languages.

(Of course feel free to ignore this if you are too busy.)

Is the task adding translation for changes in #42834?

I translated the documentation changes into Russian at #42818

It's #42881 😁

Yes.

Is the task adding translation for changes in #42834?

I translated the documentation changes into Russian at #42818

It's #42881 😁

Fixed. Sorry, i made the typo.

Update: At the same time as the 3.9 release, I just removed support for 2.8.

I delayed the deprecation for two reasons.

1 General covid-19 delay.

1. We're in the midst of switching the types-publisher infrastructure to a monorepo that publishes to the namespace @definitelytyped/*. The version update is now part of the that monorepo. Unfortunately we're still waiting on the MS open source office to make the monorepo open source, but it should be soon.

Even though the 4.0 release won't be in May, I'll still remove support for 2.9 in May as planned. It should be quite a bit easier with the new setup.