Adds docs + scripts for deployment to TypeScript

Author: orta

README.md

@@ -4,9 +4,9 @@ This tool is used to generate the web-based `lib.dom.d.ts` file which is include
 
 ## Why is my fancy API still not available here?
 
-A feature needs to be supported by more than two major browser engines to be included here, to make sure there is a good consensus among vendors: __Gecko__ (Firefox), __Blink__ (Chrome/Edge), and __WebKit__ (Safari).
+A feature needs to be supported by two or more major browser engines to be included here, to make sure there is a good consensus among vendors: __Gecko__ (Firefox), __Blink__ (Chrome/Edge), and __WebKit__ (Safari).
 
-If the condition is met but still is not available here, please [file an issue](hthttps://github.com/microsoft/TypeScript-DOM-lib-generator/issues/new).
+If the condition is met but still is not available here, first check the heuristics below and then please [file an issue](hthttps://github.com/microsoft/TypeScript-DOM-lib-generator/issues/new).
 
 ## Build Instructions
 
@@ -28,13 +28,13 @@ To test:
 npm run test
 ```
 
-To deploy:
 
-```sh
-npm run migrate
-```
+## `@types/[lib]` to TypeScript Versions
 
-The script will look in for a clone of the TypeScript repo in "../TypeScript", or "./TypeScript" to move the generated files in. 
+| `@types/[lib]` version | TypeScript Version  | Minimum TypeScript Support |
+| ---------------------------------------------------------------------- | ----------- | -------------- |
+| `@types/web` [0.0.1](https://www.npmjs.com/package/@types/web/v/0.0.1) | ~4.3        | 4.4            |
+| `@types/web` [0.0.2](https://www.npmjs.com/package/@types/web/v/0.0.2) | ~4.4 beta   | 4.4            |
 
 ## Contribution Guidelines
 
@@ -116,3 +116,26 @@ To give you a sense of whether we will accept changes, you can use these heurist
 - `removedTypes.json`: types that are defined in the spec file but should be removed.
 - `comments.json`: comment strings to be embedded in the generated .js files.
 - `deprecatedMessage.json`: the reason why one type is deprecated. The reason why it is a separate file rather than merge in comment.json is mdn/apiDescriptions.json would also possibly be deprecated.
+
+## Deployment to TypeScript
+
+To migrate the *.d.ts files into TypeScript:
+
+1. Run:
+
+    ```sh
+    npm run migrate -- [previous_types_web_version]
+    ```
+
+    The script will look in for a clone of the TypeScript repo in "../TypeScript", or "./TypeScript" to move the generated files in. Or migrate the files manually, you do you.
+
+1. Update the README table with the mappings for versions in the `@types/[lib]`. E.g. TS 4.5 -> `@types/web` `0.0.23`.
+
+1. Generate a CHANGELOG for the releases:
+
+    ```sh
+    #                       lib        from  to
+    npm run ts-changelog -- @types/web 0.0.2 0.0.23
+    ```
+
+1. Add the CHANGELOG to the release issue

src/migrate.ts deploy/migrate.mjs

@@ -16,6 +16,7 @@ if (!tscWD)
 
 const generatedFiles = readdirSync("generated");
 generatedFiles.forEach((file) => {
+  if (file == ".DS_Store") return;
   const contents = readFileSync(join("generated", file), "utf8");
   const newFilePath = join(tscWD, "src", "lib", file);
   writeFileSync(newFilePath, contents);

deploy/versionChangelog.mjs

@@ -0,0 +1,37 @@
+// @ts-check
+
+// npm run ts-changelog @types/web 0.0.1 0.0.3
+
+import { generateChangelogFrom } from "../lib/changelog.js";
+import fetch from "node-fetch";
+
+const [name, before, to] = process.argv.slice(2);
+if (!name || !before || !to) {
+  throw new Error(
+    "Expected three arguments: package name, version before, version to"
+  );
+}
+
+const go = async () => {
+  const allFiles = `https://unpkg.com/${name}/?meta`;
+  const npmFileReq = await fetch(allFiles);
+  const npmDTSFiles = await npmFileReq.json();
+  const dtsFiles = npmDTSFiles.files.filter((f) => f.path.endsWith(".d.ts"));
+
+  for (const file of dtsFiles) {
+    const beforeURI = `https://unpkg.com/${name}@${before}${file.path}`;
+    const npmBeforeFileReq = await fetch(beforeURI);
+    const npmBeforeFileText = await npmBeforeFileReq.text();
+
+    const toURI = `https://unpkg.com/${name}@${to}${file.path}`;
+    const npmToFileReq = await fetch(toURI);
+    const npmToFileText = await npmToFileReq.text();
+
+    const title = `\n## \`${file.path.slice(1)}\`\n`;
+    const notes = generateChangelogFrom(npmBeforeFileText, npmToFileText);
+
+    console.log(title);
+    console.log(notes.trim() === "" ? "No changes" : notes);
+  }
+};
+go();

package.json

@@ -20,7 +20,8 @@
     "lint": "eslint --max-warnings 0 src",
     "test": "npm run lint && npm run build && node ./lib/test.js && node ./unittests/index.js",
     "changelog": "tsc && node ./lib/changelog.js",
-    "migrate": "node ./lib/migrate.js",
+    "ts-changelog": "node ./deploy/versionChangelog.mjs",
+    "migrate": "node ./deploy/migrate.mjs",
     "version": "npm i && tsc && node ./lib/version.js"
   },
   "author": {