Document how to add a new browser version to BCD (#20340)

* Document how to add a new browser version to BCD * Update docs/data-guidelines/browsers.md Co-authored-by: Florian Scholz <[email protected]> --------- Co-authored-by: Florian Scholz <[email protected]>
mdn · Jul 19, 2023 · 02212cb · 02212cb
1 parent 99c4a4d
commit 02212cb
Show file tree

Hide file tree

Showing 2 changed files with 38 additions and 11 deletions.
diff --git a/docs/data-guidelines/browsers.md b/docs/data-guidelines/browsers.md
@@ -10,6 +10,44 @@ If the table indicates an initial version of "1" and an information source says
 
 This guideline was proposed in [#6861](https://github.com/mdn/browser-compat-data/pull/6861).
 
+## Adding new browser versions
+
+When a browser releases a new major or minor version, we will want to add it to our browser data. In some cases, the new browser version may already be defined, and we simply need to mark it as the current version.
+
+To add a new browser release:
+
+1. Open the relevant JSON file within the `browsers/` folder (ex. `browsers/chrome.json` for Google Chrome)
+2. In the `browsers.[browser_id].releases` object...
+   1. ...add a new entry with the version number as the key, referencing the [schema](../../schemas/browsers-schema.md#releases)
+   2. ...update the existing entry if it exists.
+3. Set the `status` of the current browser to `"current"`
+   - If you are adding a beta browser release, set the `status` to `"beta"`
+4. Set the `status` of the previous browser release to `"retired"`
+   - If you are adding a beta browser release, skip this step
+
+You should only add releases with major and minor semver bump. See [Choosing a version number](./index.md#choosing-a-version-number) for more details.
+
+### Node.js
+
+Node.js follows a different release cycle than most software. Every even-numbered major release (ex. v14, v16, v18) is considered a Long-Term Support version and receives new features and bug fixes even after the next major version is released. For example, Node.js may release v16.10.0, then v17.0.0, and then v16.11.0 to backport a feature that is also introduced in v17.0.0.
+
+The most recent minor release of an LTS release of Node.js should be marked as `status: "esr"` instead of `status: "current"`; only the Node.js version with the highest version number should be marked as `status: "current"`. For example, if Node.js releases v16.10.0, v17.0.0, and v16.11.0 in that order, v17.0.0 should be marked as `status: "current"`, v16.11.0 as `status: "esr"`, and v16.10.0 as `status: "retired"`.
+
+For Node.js, new versions may be added if:
+
+- The Node.js version includes a V8 engine bump
+- It is a major semver bump (ex. v19 -> v20)
+- Support has changed for feature tracked in BCD (ex. if Node.js v14.3.0 supports a new Web API builtin, but the V8 engine is the same version)
+
+To add a new Node.js release:
+
+1. Open `browsers/nodejs.json`
+2. In the `browsers.nodejs.releases` object, add a new entry with the version number as the key, referencing the [schema](../../schemas/browsers-schema.md#releases)
+3. Set the `status` property to...
+   - ...`"current"`, if it is the version with the highest semver
+   - ...`"esr"`, if it is the latest version within that major version
+4. Set the `status` all other versions within that major version to `"retired"`
+
 ## Addition of browsers
 
 BCD's [owners](../../GOVERNANCE.md) may choose to adopt a new browser or engine. To add a new browser to BCD, we need evidence of (in decreasing order of importance):

diff --git a/docs/data-guidelines/index.md b/docs/data-guidelines/index.md
@@ -1,17 +1,6 @@
 # Data guidelines
 
 This folder contains guidelines to help you record data in a consistent and understandable way. It covers the project's requirements for the way features should be represented, including requirements that are not coded into the linter or schema.
-
-<!-- BEGIN TEMPLATE --
-
-## Short title in sentence case
-
-A description of what to do, preferably in the imperative. If applicable, include an example to illustrate the rule.
-
-If it's helpful to understanding the rule, summarize the rationale. Definitely cite the issue or pull request where this was decided (it may be the PR that merges the policy).
-
--- END TEMPLATE -->
-
 This file contains general guidelines that apply to all features added to BCD. For guidelines that apply to specific categories of data, check out their respective files within this folder.
 
 - [API](./api.md)