Provide an approved method to get a status for a single BCD key #1204

ddbeck · 2024-06-06T12:55:18Z

This adds an approved method, called getStatus(), to turn a web-features ID and a BCD key into a status for that specific BCD key.

Right now, this method is a formalism: it doesn't actually check that the BCD key is part of the named feature (or that the named feature even exists). But this illustrates the overall principle and will let us actually clamp down in follow up PRs, if this is the right approach.

Towards #979.

ddbeck · 2024-06-06T12:55:40Z

Note that this probably needs owner's group consensus before merging.

ddbeck · 2024-06-06T13:57:31Z

See also: #1173 (comment)

captainbrosset

I'm generally in favor of this approach. Just left a few comments.

packages/compute-baseline/README.md

captainbrosset · 2024-06-07T07:38:45Z

packages/compute-baseline/README.md

-  },
-  compat,
-);
+getStatus("fetch", "api.Response.json", compat);


Can you help me understand when someone would need to use their own compat data? Are there other data sources out there that match the BCD schema and which getStatus would be able to work with?

If this is a valid use case, then I would suggest not using the getStatus method for it, since getStatus is for blessed/editorial reviewed Baseline statuses only. But if you use your own data, then we can't guaranty anything about it.

I think this is for MDN to make sure that they use the same BCD for Baseline status and the compat tables. I'm not sure what their setup is though, it could be that they get this automatically simply by having the project (yari) depend on one version of BCD.

Yes, I was trying to accommodate (for example) MDN upgrading BCD independently of web-features. Really, I'd like to be able to say something like: "You can use any version of BCD >= web-features's version of BCD" but we don't currently provide that information to consumers of web-features.

Another route here is to leave this usage undocumented.

Upon further consideration, I've decided to undo this change in the example. Really, consumers ought to use the latest BCD unless/until we can do some more clever enforcement.

captainbrosset · 2024-06-07T07:39:58Z

packages/compute-baseline/src/baseline/index.ts

+  // TODO: actually check that featureId is a valid feature
+  // TODO: actually check that compatKey is tagged as featureId in BCD _or_ listed in web-features


Are you planning on implementing those TODOs in this PR?

I am not. This requires some non-trivial changes to the way the repo and dependencies are set up, which would overwhelm the policy and documentation changes going on here.

foolip · 2024-06-07T12:53:21Z

packages/compute-baseline/README.md

-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.


In order for this to be accurate, we need a way to review the individual statuses. Grouping compat keys by their generated status with comments is the approach we've discussed.

packages/compute-baseline/README.md

foolip · 2024-06-07T12:57:32Z

packages/compute-baseline/README.md

-  },
-  compat,
-);
+getStatus("fetch", "api.Response.json", compat);


I think this is for MDN to make sure that they use the same BCD for Baseline status and the compat tables. I'm not sure what their setup is though, it could be that they get this automatically simply by having the project (yari) depend on one version of BCD.

foolip · 2024-06-07T13:00:00Z

packages/compute-baseline/src/baseline/index.ts

+  // TODO: actually check that compatKey is tagged as featureId in BCD _or_ listed in web-features
+  return JSON.parse(
+    computeBaseline(
+      { compatKeys: [compatKey], checkAncestors: true },


Can you add a test that shows the difference between checkAncestors being true or false? Is it about flags that aren't correctly cascaded?

This is already tested with

web-features/packages/compute-baseline/src/baseline/index.test.ts

Lines 78 to 104 in cc5cccb

it("finds discrepancies with ancestors (checkAncestors)", function () {

const result = computeBaseline({

compatKeys: ["api.Notification.body"],

checkAncestors: false,

});

const resultExplicit = computeBaseline({

compatKeys: ["api.Notification", "api.Notification.body"],

checkAncestors: false,

});

const resultWithAncestors = computeBaseline({

compatKeys: ["api.Notification.body"],

checkAncestors: true,

});

assert.equal(resultExplicit.toJSON(), resultWithAncestors.toJSON());

assert.notEqual(result.toJSON(), resultWithAncestors.toJSON());

assert.notEqual(result.baseline, resultWithAncestors.baseline);

assert.notEqual(

result.baseline_low_date?.toString(),

resultWithAncestors.baseline_low_date?.toString(),

);

chai.expect(result).to.matchSnapshot();

chai.expect(resultExplicit).to.matchSnapshot();

chai.expect(resultWithAncestors).to.matchSnapshot();

});

. Do you want another test to confirm that getStatus does the same?

Ah, existing tests are OK.

Co-authored-by: Patrick Brosset <patrickbrosset@gmail.com>

ddbeck · 2024-06-10T15:58:05Z

Hi folks, I tagged the current owners for review. I brought this PR up on the last WebDX call (and the idea in general in previous web-features/Baseline calls), since it's a little bit of a departure from how we've done editorial review so far. I suspect this is getting close to landing, so if any of the owners want to personally review it before we move forward, I wanted to make sure there was an explicit opportunity for that. Thank you!

foolip · 2024-06-12T23:06:58Z

packages/compute-baseline/src/baseline/index.ts

+  featureId: string,
+  compatKey: string,
+  compat: Compat = defaultCompat,
+) {


Can you add the return type here? It looks like it's not the same as computeBaseline, and I wonder if that's intentional.

Done with 63e00ad. (Sorting out the peer dependency between compute-baseline and web-features will be fussy. Saving it for a PR just for that.)

atopal

LGTM!

ddbeck · 2024-06-17T14:12:17Z

Thanks to everyone who had a look at this (or listened to me ramble on about it in the WebDX call last week)!

ddbeck added 2 commits June 6, 2024 14:59

Add blessed Baseline calculation method

53fd8ba

Document blessed Baseline calculation method

ca8bd79

ddbeck force-pushed the 979-bless-compute-baseline branch from 1692cc8 to ca8bd79 Compare June 6, 2024 12:59

Bump compute-baseline verison

4ddd085

ddbeck mentioned this pull request Jun 6, 2024

Allow overlapping BCD keys without creating ambiguity #1173

Open

captainbrosset reviewed Jun 7, 2024

View reviewed changes

foolip reviewed Jun 7, 2024

View reviewed changes

foolip mentioned this pull request Jun 7, 2024

Add support to "pin" a feature's support to its entrypoint(s) #1216

Closed

ddbeck and others added 4 commits June 10, 2024 16:05

Add description to getStatus example

a1ad8d7

Co-authored-by: Patrick Brosset <patrickbrosset@gmail.com>

Add TODO to provide a better example for getStatus

032d809

Caution against unapproved examples

92224bd

Revert example for bringing your own data

073b991

ddbeck requested review from captainbrosset, foolip, dfabulich, jgraham, Elchi3, Fyrd, atopal and LeoMcA June 10, 2024 15:53

foolip approved these changes Jun 11, 2024

View reviewed changes

foolip mentioned this pull request Jun 11, 2024

Group BCD keys in dist by status block #1231

Merged

ddbeck mentioned this pull request Jun 11, 2024

Introduce compute_from to pin a feature's status to BCD key(s) #1227

Merged

Merge branch 'main' into 979-bless-compute-baseline

566bb80

foolip reviewed Jun 12, 2024

View reviewed changes

captainbrosset approved these changes Jun 13, 2024

View reviewed changes

foolip mentioned this pull request Jun 13, 2024

More features faster blockers #1240

Closed

5 tasks

Add type to getStatus

63e00ad

atopal approved these changes Jun 13, 2024

View reviewed changes

Merge branch 'main' into 979-bless-compute-baseline

7d496a4

ddbeck enabled auto-merge (squash) June 17, 2024 14:11

ddbeck merged commit 223983d into web-platform-dx:main Jun 17, 2024
3 checks passed

ddbeck deleted the 979-bless-compute-baseline branch June 17, 2024 14:12

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Provide an approved method to get a status for a single BCD key #1204

Provide an approved method to get a status for a single BCD key #1204

ddbeck commented Jun 6, 2024

ddbeck commented Jun 6, 2024

ddbeck commented Jun 6, 2024

captainbrosset left a comment

captainbrosset Jun 7, 2024

foolip Jun 7, 2024

ddbeck Jun 10, 2024

ddbeck Jun 10, 2024

captainbrosset Jun 7, 2024

ddbeck Jun 10, 2024

foolip Jun 7, 2024

foolip Jun 7, 2024

foolip Jun 7, 2024

ddbeck Jun 10, 2024

foolip Jun 11, 2024

ddbeck commented Jun 10, 2024

foolip Jun 12, 2024

ddbeck Jun 13, 2024

atopal left a comment

ddbeck commented Jun 17, 2024

		// TODO: actually check that featureId is a valid feature
		// TODO: actually check that compatKey is tagged as featureId in BCD _or_ listed in web-features

	it("finds discrepancies with ancestors (checkAncestors)", function () {
	const result = computeBaseline({
	compatKeys: ["api.Notification.body"],
	checkAncestors: false,
	});
	const resultExplicit = computeBaseline({
	compatKeys: ["api.Notification", "api.Notification.body"],
	checkAncestors: false,
	});
	const resultWithAncestors = computeBaseline({
	compatKeys: ["api.Notification.body"],
	checkAncestors: true,
	});

	assert.equal(resultExplicit.toJSON(), resultWithAncestors.toJSON());
	assert.notEqual(result.toJSON(), resultWithAncestors.toJSON());

	assert.notEqual(result.baseline, resultWithAncestors.baseline);
	assert.notEqual(
	result.baseline_low_date?.toString(),
	resultWithAncestors.baseline_low_date?.toString(),
	);

	chai.expect(result).to.matchSnapshot();
	chai.expect(resultExplicit).to.matchSnapshot();
	chai.expect(resultWithAncestors).to.matchSnapshot();
	});

Provide an approved method to get a status for a single BCD key #1204

Provide an approved method to get a status for a single BCD key #1204

Conversation

ddbeck commented Jun 6, 2024

ddbeck commented Jun 6, 2024

ddbeck commented Jun 6, 2024

captainbrosset left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ddbeck commented Jun 10, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

atopal left a comment

Choose a reason for hiding this comment

ddbeck commented Jun 17, 2024