Tag Releases for Easier Versioning

[DanielRosenwasser]

Today, the DOM types are auto-deployed to npm, but the story there is extremely confusing. If breaks are introduced in a newer version of TypeScript, we can tell users to lock down their DOM types with @types/web, but there's no easy way to tell which version of @types/web corresponds to a specific version of TypeScript.

We need to come up with some stable scheme where

• TypeScript's (stable) publishing process has a corresponding release (or tag for an existing release) for @types/web.
• a tag should be relatively easy to identify - something like npm install @types/[email protected]
• The tagging mechanism should also correspond to that of @types packages from DefinitelyTyped.

[orta]

FWIW, there is the table in the README of this project which lists the versions - https://github.com/microsoft/TypeScript-DOM-lib-generator#typeslib-to-typescript-versions

You can also extend the deploy process I used https://github.com/microsoft/TypeScript-DOM-lib-generator#deployment-to-typescript to generate tags and/or update the README though.

I avoided automating this part because it's not guaranteed that the PR send from the DOM version would get merged (too breaky, and/or required DOM changes to get merged)

That could probably be improved by having the DOM -> TSC process leave a commit or tag inside the TSC repo and then on a TSC release you could have it re-use that commit/tag to make the connection from typescript back to the DOM types. Maybe be a custom header in lib.dom.d.ts which lets people link to the DOM repo at the exact commit/tag which is pretty useful for everyone.

[xiaoxiangmoe]

Do all the built-in type libraries, including lib.es5.d.ts lib.webworker.d.ts, etc. need to be added in @types/web or some lib like @types/ecmascript?

[orta]

Nah. @types/web just accounts for the DOM APIS - you can override any lib using the techniques documented in https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html#supporting-lib-from-node_modules

I think it's a reasonable assumption for types/web that someone has the baseline JS types set up

[mrienstra]

I'd like to update the README to include 4.8 & 4.9 beta (though I guess beta hasn't hit a proper release yet?), but I'm not confident about how to go about matching up versions.

Jul 02, 2022: @types/[email protected] Jul 25, 2022: @types/[email protected] Aug 03, 2022: @types/[email protected] Aug 18, 2022: @types/[email protected] Sep 17, 2022: @types/[email protected] Sep 21, 2022: @types/[email protected] Sep 23, 2022: @types/[email protected]

July 20, 2022: v4.8-rc Update DOM lib for 4.8 RC June 17, 2022: v4.8-beta Update 4.8 DOM from Typescript-DOM-lib-generator Sep 21, 2022: v? DOM update 2022/09/21

August 11, 2022: 4.8 rc Aug 25, 2022: 4.8

OK, let's see, PictureInPictureEvent was added in @types/[email protected], but didn't show up in TypeScript's dom.generated.d.ts until DOM update 2022/09/21, so presumably @types/[email protected] goes with both 4.8 rc & 4.8. I'll open a PR for that.

[eligrey]

If @types/web is only for "DOM APIs" then why is it @types/web and not @types/dom? I would expect @types/web to include all Web Platform API types. I believe that many of the current built-ins should also be moved to such a package.

[saschanaz]

It's not for "DOM APIs" but for general web APIs that are exposed in the main thread. DOM-lib here is just some legacy way to call the lib, which IMO should be replaced at some point.