Feedback and a good README

Author: orta

.github/workflows/deploy.yml

@@ -30,4 +30,5 @@ jobs:
         run: node deploy/deployChangedPackages.mjs
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 

deploy/createTypesPackages.mjs

@@ -7,6 +7,7 @@ const packages = [
     {
       name: "@types/web",
       description: "Types for the DOM, and other web technologies in browsers",
+      readme: "./readmes/web.md",
       files: [
         { from: "../generated/dom.generated.d.ts", to: "index.d.ts" }
       ],
@@ -20,6 +21,7 @@ const packages = [
 import { join, dirname } from "path";
 import fs from "fs";
 import { fileURLToPath } from "url";
+import semver from "semver";
 import pkg from "prettier";
 const { format } = pkg;
 import { execSync } from "child_process";
@@ -58,9 +60,11 @@ const go = async () => {
       );
     });
 
-    // Setup the files
-    await updatePackageJSON(packagePath, pkg, gitSha);
+    // Setup the files in the repo
+    const newPkgJSON = await updatePackageJSON(packagePath, pkg, gitSha);
+    copyREADME(pkg, newPkgJSON, join(packagePath, "README.md"));
 
+    // Done
     console.log("Built:", pkg.name);
   }
 };
@@ -89,7 +93,7 @@ async function updatePackageJSON(packagePath, pkg, gitSha) {
       Number(semverMarkers[2]) + 1
     }`;
 
-    if (isBumpedVersionHigher(version, bumpedVersion)) {
+    if (semver.gt(version, bumpedVersion)) {
       version = bumpedVersion;
     }
   } catch (error) {
@@ -103,20 +107,23 @@ async function updatePackageJSON(packagePath, pkg, gitSha) {
     pkgJSONPath,
     format(JSON.stringify(packageJSON), { filepath: pkgJSONPath })
   );
+
+  return packageJSON;
 }
 
-/**
- * @param packageJSONVersion {string}
- * @param bumpedVersion {string}
- */
-function isBumpedVersionHigher(packageJSONVersion, bumpedVersion) {
-  const semverMarkersPackageJSON = packageJSONVersion.split(".");
-  const semverMarkersBumped = bumpedVersion.split(".");
-  for (let i = 0; i < 3; i++) {
-    if (Number(semverMarkersPackageJSON[i]) > Number(semverMarkersBumped[i])) {
-      return false;
-    }
-  }
+// Copies the README and adds some rudimentary templating to the file.
+function copyREADME(pkg, pkgJSON, writePath) {
+  let readme = fs.readFileSync(join(__filename, "..", pkg.readme), "utf-8");
+
+  const htmlEncodedTag =
+    encodeURIComponent(pkgJSON.name) + "%40" + pkgJSON.version;
+
+  readme = readme
+    .replace("{{version}}", pkgJSON.version)
+    .replace(
+      "{{release_href}}",
+      `https://github.com/microsoft/TypeScript-DOM-lib-generator/releases/tag/${htmlEncodedTag}`
+    );
 
-  return true;
+  fs.writeFileSync(writePath, readme);
 }

deploy/deployChangedPackages.mjs

@@ -1,6 +1,7 @@
 // @ts-check
 
 // node deploy/deployChangedPackages.mjs
+
 // Builds on the results of createTypesPackages.mjs and deploys the
 // ones which have changed.
 
@@ -9,13 +10,24 @@ import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import fetch from "node-fetch";
 import { spawnSync } from "child_process";
+import { Octokit } from "@octokit/core";
 
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-ignore
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+const verify = () => {
+  const authToken = process.env.GITHUB_TOKEN || process.env.GITHUB_API_TOKEN;
+  if (!authToken)
+    throw new Error(
+      "There isn't an ENV var set up for creating a GitHub release, expected GITHUB_TOKEN."
+    );
+};
+
 const go = async () => {
+  verify();
+
   const uploaded = [];
 
   // Loop through generated packages, deploying versions for anything which has different
@@ -36,14 +48,18 @@ const go = async () => {
     for (const file of dtsFiles) {
       const generatedDTSPath = join(generatedDir, dirName, file);
       const generatedDTSContent = fs.readFileSync(generatedDTSPath, "utf8");
+      const unpkgURL = `https://unpkg.com/${pkgJSON.name}/${file}`;
       try {
-        const unpkgURL = `https://unpkg.com/${pkgJSON.name}/${file}`;
         const npmDTSReq = await fetch(unpkgURL);
         const npmDTSText = await npmDTSReq.text();
         upload = upload || npmDTSText !== generatedDTSContent;
       } catch (error) {
-        // Not here, definitely needs to be uploaded
-        upload = true;
+        // Could not find a previous build
+        console.log(
+          `Could not get the file ${file} inside the npm package ${pkgJSON.name} from unpkg at ${unpkgURL}`
+        );
+        process.exitCode = 1;
+        upload = false;
       }
     }
 
@@ -60,6 +76,8 @@ const go = async () => {
           process.exit(publish.status);
         } else {
           console.log(publish.stdout?.toString());
+
+          await createRelease(`${pkgJSON.name}@${pkgJSON.version}`);
         }
       }
 
@@ -81,4 +99,16 @@ const go = async () => {
   }
 };
 
+async function createRelease(tag) {
+  const authToken = process.env.GITHUB_TOKEN || process.env.GITHUB_API_TOKEN;
+  const octokit = new Octokit({ auth: authToken });
+
+  await octokit.request("POST /repos/{owner}/{repo}/releases", {
+    owner: "microsoft",
+    repo: "TypeScript-DOM-lib-generator",
+    tag_name: tag,
+    target_commitish: process.env.GITHUB_SHA,
+  });
+}
+
 go();

deploy/readmes/web.md

@@ -0,0 +1,33 @@
+### `@types/web` - Types for the DOM and most web-related APIs
+
+This module contains the DOM types for the majority of the web APIs used in a web browser. 
+
+The APIs inside `@types/web` are generated from the specifications for CSS, HTML and JavaScript. Given the size and state of constant change in web browsers, `@types/web` only has APIs which have passed a certain level of standardization and are available in at least two different browser engines. 
+ 
+`@types/web` is also included inside TypeScript, available as `dom` in the [`lib`](https://www.typescriptlang.org/tsconfig#lib) section and included in projects by default. By using `@types/web` you can lock your the web APIs used in your projects, easing the process of updating TypeScript and offering more control in your environment. 
+
+## Installation 
+
+To use `@types/web` you need to do two things:
+
+1. Install the dependency: `npm install @types/web --save-dev`, `yarn add @types/web --dev` or `pnpm add @types/web --dev`.
+
+1. Update your [`tsconfig.json`](https://www.typescriptlang.org/tsconfig). There are two cases to consider depending on if you have `lib` defined in your `tsconfig.json` or not.
+
+    1. **Without "lib"** - You will need to add `"lib": []`. The value you want to add inside your lib should correlate to your [`"target"`](https://www.typescriptlang.org/tsconfig#target). For example if you had `"target": "es2017"`, then you would add `"lib": ["es2017"]`
+    1. **With "lib"**  - You should remove `"dom"`.
+
+That's all. 
+
+## SemVer
+
+This project does not respect semantic versioning as almost every change could potentially break a project, though we try to minimize removing types. 
+`@types/web` follow the specifications, so when they mark a function/object/API/type as deprecated or removed - that is respected.
+
+## TypeScript Version Support
+
+Prior to `@types/web` the web APIs were deployed with a version of TypeScript, and backwards compatibility has not been a concern. Now the web APIs and TypeScript can be de-coupled, then we expect to eventually hit a point where we take backwards compatibility in mind. For now, `@types/web` officially supports TypeScript 4.4 and above. It very likely will work with TypeScript versions much earlier that that however.
+
+## Deploy Metadata
+
+You can read what changed in version {{version}} at {{release_href}}.

deploy/template/README.md

@@ -17,6 +17,7 @@
   },
   "dependencies": {
     "@mdn/browser-compat-data": "2.0.7",
+    "@octokit/core": "^3.5.1",
     "@types/jsdom": "^16.2.10",
     "@types/node": "^15.6.1",
     "@types/node-fetch": "^2.5.10",
@@ -33,6 +34,7 @@
     "parse-diff": "^0.8.1",
     "prettier": "^2.3.0",
     "print-diff": "^1.0.0",
+    "semver": "^7.3.5",
     "styleless-innertext": "^1.1.3",
     "typescript": "^4.3.0-dev.20210327",
     "webidl2": "^24.1.1"