From ca8bd79a26dd96a8d296da1dac6b9d4b440dbc53 Mon Sep 17 00:00:00 2001
From: "Daniel D. Beck" <daniel@ddbeck.com>
Date: Thu, 6 Jun 2024 14:44:31 +0200
Subject: [PATCH] Document blessed Baseline calculation method

---
 packages/compute-baseline/README.md           | 52 +++++++++++++------
 .../compute-baseline/src/baseline/index.ts    |  7 +--
 2 files changed, 40 insertions(+), 19 deletions(-)

diff --git a/packages/compute-baseline/README.md b/packages/compute-baseline/README.md
index 4e057a9218f..5ab970e0fcf 100644
--- a/packages/compute-baseline/README.md
+++ b/packages/compute-baseline/README.md
@@ -2,23 +2,21 @@
 
 By the [W3C WebDX Community Group](https://www.w3.org/community/webdx/) and contributors.
 
-`compute-baseline` computes preliminary [Baseline statuses](https://github.com/web-platform-dx/web-features/blob/main/docs/baseline.md) from `@mdn/browser-compat-data` feature keys.
+`compute-baseline` computes [Baseline statuses](https://github.com/web-platform-dx/web-features/blob/main/docs/baseline.md) from `@mdn/browser-compat-data` feature keys.
 You can use `compute-baseline` to help you find interoperable web platform features, propose new [`web-features`](https://github.com/web-platform-dx/web-features/) features, or compare support between features.
 
 `compute-baseline` also provides utility classes for working with `@mdn/browser-compat-data` generally.
 
 ## Limitations
 
-If you need authoritative Baseline statuses, check out the [`web-features`](https://github.com/web-platform-dx/web-features/tree/main/packages/web-features) package instead.
+If you need authoritative Baseline statuses, check out the [`web-features`](https://github.com/web-platform-dx/web-features/tree/main/packages/web-features) package first.
+Most of the time, the status information provided by `web-features` is the best representation of a feature overall.
 
-Don't use `compute-baseline` to generate publishable Baseline statuses for arbitrary web platform features.
-The results of `compute-baseline` invocations have _not_ received editorial review.
-Strictly speaking, a Baseline status requires editorial review, so statuses generated by `compute-baseline` are tentative.
-If you need authoritative Baseline statuses, check out the [`web-features`](https://github.com/web-platform-dx/web-features/tree/main/packages/web-features) package instead.
-
-You can use `compute-baseline` to explore possibilities or do error correction.
-For example, you might use `compute-baseline` to hide a Baseline status, when showing a broader feature's status might be misleading.
+If you need to know the Baseline status of a specific browser compatibility data entry within a `web-features` feature, then you can use the `getStatus` method.
+The `web-features` package and the `getStatus` method are the **only** ways to get a status that have completed the full Baseline editorial review process.
 
+All other invocations of `compute-baseline` have _not_ received editorial review.
+Don't use `compute-baseline` to generate publishable Baseline statuses for arbitrary web platform features.
 If you're not sure whether your application fits with the definition of Baseline, please [file an issue](https://github.com/web-platform-dx/web-features/issues/new).
 
 ## Prerequisites
@@ -40,6 +38,33 @@ Run:
 
 ## Usage
 
+### Get a Baseline status for a portion of a feature
+
+```javascript
+import { getStatus } from "compute-baseline";
+
+getStatus("fetch", "api.Response.json");
+```
+
+Returns:
+
+```
+{
+  baseline: 'high',
+  baseline_low_date: '2017-03-27',
+  baseline_high_date: '2019-09-27',
+  support: {
+    chrome: '42',
+    chrome_android: '42',
+    edge: '14',
+    firefox: '39',
+    firefox_android: '39',
+    safari: '10.1',
+    safari_ios: '10.3'
+  }
+}
+```
+
 ### Check support for a group of compat keys
 
 ```javascript
@@ -92,17 +117,12 @@ If you don't want to import `@mdn/browser-compat-data` as your data source, you
 
 ```javascript
 import data from "some-parsed-json-file";
-import { computeBaseline } from "compute-baseline";
+import { getStatus } from "compute-baseline";
 import { Compat } from "compute-baseline/browser-compat-data";
 
 const compat = new Compat(data);
 
-computeBaseline(
-  {
-    compatKeys: ["css.properties.border-color"],
-  },
-  compat,
-);
+getStatus("fetch", "api.Response.json", compat);
 ```
 
 <!-- TODO: API reference -->
diff --git a/packages/compute-baseline/src/baseline/index.ts b/packages/compute-baseline/src/baseline/index.ts
index 5da0f7af61e..8faa10bf740 100644
--- a/packages/compute-baseline/src/baseline/index.ts
+++ b/packages/compute-baseline/src/baseline/index.ts
@@ -46,9 +46,10 @@ interface SupportStatus {
 
 /**
  * Calculate a Baseline status for specific browser compat data keys within a
- * web-features feature. Use this method to calculate fine-grained support
- * statuses. This is the only method approved to compute Baseline statuses not
- * otherwise published in the `web-features` package.
+ * web-features feature, in the style of a web-feature's `status` key. Use this
+ * method to calculate fine-grained support statuses. This is the only method
+ * approved to compute Baseline statuses not otherwise published in the
+ * `web-features` package.
  *
  * For example, suppose you want to show a Baseline status for a specific method
  * in a feature, which might've been supported earlier or later than the broader