Merge pull request #1057 from microsoft/release_docs

Documents the release to TS process, and adds support for easily generating a CHANGELOG for 2 arbitrary versions

Author: Orta Therox

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 renamed to 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,39 @@
+// @ts-check
+
+// npm run ts-changelog @types/web 0.0.1 0.0.3
+
+import { generateChangelogFrom } from "../lib/changelog.js";
+import { packages } from "./createTypesPackages.mjs";
+import { execSync } from "child_process";
+import { basename } from "path";
+
+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 = () => {
+  // We'll need to map back from the filename in the npm package to the
+  // generated file in baselines inside the git tag
+  const thisPackageMeta = packages.find((p) => p.name === name);
+  if (!thisPackageMeta)
+    throw new Error(`Could not find ${name} in ${packages.map((p) => p.name)}`);
+
+  for (const file of thisPackageMeta.files) {
+    const filename = `baselines/${basename(file.from)}`;
+    const beforeFileText = gitShowFile(`${name}@${before}`, filename);
+    const toFileText = gitShowFile(`${name}@${to}`, filename);
+
+    const notes = generateChangelogFrom(beforeFileText, toFileText);
+
+    console.log(`\n## \`${file.to}\`\n`);
+    console.log(notes.trim() === "" ? "No changes" : notes);
+  }
+};
+
+const gitShowFile = (commitish, path) =>
+  execSync(`git show "${commitish}":${path}`, { encoding: "utf-8" });
+
+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": {