New obsoletedBy and formerNames properties (#1018)

The new optional `obsoletedBy` property makes it possible to identify specs that
replace a given discontinued spec in the list, as discussed in #1006. The term
`obsoletedBy` was preferred over `replacedBy` because the latter is not
fantastic to convey the integration of a spec into another one, and because
Specref uses that term.

The new optional `formerNames` property makes it possible to list former
shortnames of a spec in browser-specs.

Both properties are useful, and needed, for browser-specs to act as a source of
specs for Specref. Other projects may also use these properties to track a spec
over time.

Both properties must be set in `specs.json` and are copied over to `index.json`.

This update sets the `obsoletedBy` property on the discontinued Close Watcher
API spec to target the HTML spec. The `formerNames` property is not set on any
spec for the time being.

This update also re-introduces the Resizable ArrayBuffer proposal as a
discontinued spec obsoleted by ECMAScript. This is again needed for Specref, as
deleting the spec from browser-specs broke Specref's build, see:
  tobie/specref#752

CONTRIBUTING.md

@@ -102,6 +102,11 @@ may be one of `"reset"` to start from an empty list, `"+browser"` to add
 `"browser"` to the list, and `"-browser"` to remove `"browser"` from the list.
 - `standing`: the spec's standing if default rule would not set it properly,
 see [`standing`](README.md#standing).
+- `obsoletedBy`: a list of shortnames to identify specs that replace or
+otherwise obsolete a discontinued spec, see
+[`obsoletedBy`](README.md#obsoletedby).
+- `formerNames`: a list of shortnames that were used to identify the spec, see
+[`formerNames`](README.md#formernames).
 
 You should **only** set these properties when they are required to generate the
 right info. For instance, some of these properties are needed for Media Queries

README.md

@@ -20,6 +20,8 @@ cross-references, WebIDL, quality, etc.
   - [`shortTitle`](#shorttitle)
   - [`categories`](#categories)
   - [`standing`](#standing)
+  - [`obsoletedBy`](#obsoletedby)
+  - [`formerNames`](#formernames)
   - [`series`](#series)
     - [`series.shortname`](#seriesshortname)
     - [`series.currentSpecification`](#seriescurrentspecification)
@@ -218,6 +220,30 @@ or `"discontinued"`. Value is always `"good"` for specs in the `browser-specs`
 package.
 
 
+### `obsoletedBy`
+
+An array that contains the list of shortnames of specs that replace or otherwise
+obsolete the contents of a discontinued spec.
+
+The `obsoletedBy` property is only set when `standing` is `"discontinued"`,
+provided that there are indeed specs that replace the contents of the spec.
+
+
+### `formerNames`
+
+An array that contains the list of shortnames that were used to identify the
+spec in the past. The property is not meant to provide an exhaustive list of all
+the shortnames that a spec ever had, but just a list of the shortnames that the
+spec used to have *in browser-specs*.
+
+By definition, shortnames listed in `formerNames` properties are not *current*
+shortnames. They can be used in projects that consume the list of specs to track
+a specification over time.
+
+The `formerNames` property is only set for specs that used to be known under a
+different `shortname` in browser-specs.
+
+
 ### `series`
 
 An object that describes the series that the spec is part of. A series includes
@@ -362,7 +388,7 @@ abandoned.
 An array that lists shortnames of known forks of the spec in the list.
 
 The `forks` property is only set when there exists at least one fork of the
-spec in the list, meaning when there is an entry in the list that has a
+spec in the list, in other words when there is an entry in the list that has a
 [`forkOf`](#forkof) property set to the spec's shortname.
 
 
@@ -473,7 +499,7 @@ Alternate URLs should only be used to ease mapping between external sources and
 specs in `browser-specs`. The canonical URL in [`nightly.url`](#nightlyurl)
 should be preferred to reference a spec otherwise.
 
-Alternate URLs are only set when needed, meaning when an alternate URL is
+Alternate URLs are only set when needed, in other words when an alternate URL is
 effectively in use in some external source and when the external source cannot
 easily be updated to use the canonical URL. In particular, the list is not meant
 to be exhaustive.

schema/definitions.json

@@ -196,6 +196,18 @@
     "standing": {
       "type": "string",
       "enum": ["good", "pending", "discontinued"]
+    },
+
+    "obsoletedBy": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/shortname" },
+      "minItems": 1
+    },
+
+    "formerNames": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/shortname" },
+      "minItems": 1
     }
   }
 }

schema/index.json

@@ -24,7 +24,9 @@
       "organization": { "$ref": "definitions.json#/$defs/organization" },
       "groups": { "$ref": "definitions.json#/$defs/groups" },
       "categories": { "$ref": "definitions.json#/$defs/categories" },
-      "standing": { "$ref": "definitions.json#/$defs/standing" }
+      "standing": { "$ref": "definitions.json#/$defs/standing" },
+      "obsoletedBy": { "$ref": "definitions.json#/$defs/obsoletedBy" },
+      "formerNames": { "$ref": "definitions.json#/$defs/formerNames" }
     },
     "required": [
       "url", "shortname", "series", "seriesComposition", "nightly",

schema/specs.json

@@ -26,6 +26,8 @@
           "groups": { "$ref": "definitions.json#/$defs/groups" },
           "categories": { "$ref": "definitions.json#/$defs/categories-specs" },
           "standing": { "$ref": "definitions.json#/$defs/standing" },
+          "obsoletedBy": { "$ref": "definitions.json#/$defs/obsoletedBy" },
+          "formerNames": { "$ref": "definitions.json#/$defs/formerNames" },
           "forceCurrent": { "type": "boolean" },
           "multipage": { "type": "boolean" }
         },

specs.json

@@ -340,6 +340,14 @@
   "https://tc39.es/proposal-json-modules/",
   "https://tc39.es/proposal-json-parse-with-source/",
   "https://tc39.es/proposal-regexp-modifiers/",
+  {
+    "url": "https://tc39.es/proposal-resizablearraybuffer/",
+    "title": "Resizable ArrayBuffer and growable SharedArrayBuffer",
+    "standing": "discontinued",
+    "obsoletedBy": [
+      "ecmascript"
+    ]
+  },
   "https://tc39.es/proposal-set-methods/",
   "https://tc39.es/proposal-shadowrealm/",
   "https://tc39.es/proposal-symbols-as-weakmap-keys/",
@@ -391,7 +399,10 @@
   {
     "url": "https://wicg.github.io/close-watcher/",
     "title": "Close Watcher API",
-    "standing": "discontinued"
+    "standing": "discontinued",
+    "obsoletedBy": [
+      "html"
+    ]
   },
   "https://wicg.github.io/compression/",
   "https://wicg.github.io/content-index/spec/",

test/index.js

@@ -230,4 +230,19 @@ describe("List of specs", () => {
         spec.nightly.sourcePath === s.nightly.sourcePath));
     assert.deepStrictEqual(wrong, [], JSON.stringify(wrong, null, 2));
   });
+
+  it("lists obsoletedBy info only for discontinued specs", () => {
+    const wrong = specs.filter(s =>
+      s.obsoletedBy &&
+      s.standing !== "discontinued"
+    );
+    assert.deepStrictEqual(wrong, []);
+  });
+
+  it("does not contain formerNames that identify actual specs", () => {
+    const wrong = specs.filter(s =>
+      s.formerNames?.find(name => specs.find(spec => spec.shortname === name))
+    );
+    assert.deepStrictEqual(wrong, []);
+  });
 });