Skip to content

Add move and split redirects to the schema #3000

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 16 commits into
base: main
Choose a base branch
from

Conversation

ddbeck
Copy link
Collaborator

@ddbeck ddbeck commented May 27, 2025

Towards #91 and the sequel to #2990.

Because this PR follows #2990, looking at the diff between them might be easier to look at. See: ddbeck/web-features@91-jsonschema-source-of-truth...ddbeck:web-features:91-redirects

This PR does the following:

This PR mostly follows the mock documentation discussed from #91 (see #91 (comment)). Some changes I made based on the discussion there:

  • The reason for changing an ID is moved, instead of renamed, to avoid implying that the ID will change any time the human-readable name field changes.
  • The to string/array of strings is now two distinct fields, target and targets, depending on the reason. This is to avoid some weirdness in using a preposition as a noun (i.e., to avoid saying silly things like "this feature has two tos") and to ensure the name of the field implies its type.

@ddbeck ddbeck added schema Schema changes, proposals, and bugs major version required This PR requires a minor version semver release (vX+1.0.0) package:web-features feature evolution Issues/PRs for describing changing feature definitions over time (as opposed to support) labels May 27, 2025
@github-actions github-actions bot added feature definition Creating or defining new features or groups of features. tools and infrastructure Project internal tooling, such as linters, GitHub Actions, or repo settings labels May 27, 2025
@ddbeck ddbeck requested a review from foolip May 27, 2025 16:31
name: WebCodecs
description: The WebCodecs API provides low-level access to individual video frames and chunks of audio samples, for full control over the way media is processed.
spec: https://w3c.github.io/webcodecs/
caniuse: webcodecs
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should split it, but the fact that this is in caniuse makes me think we should somehow keep webcodecs as well? With composite features or similar we could.

Do we have any other candidates for splitting where the existing entry is just wrong and has no value to preserve?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a good point. One thing I haven't done is to write guidelines that say when to move or split a feature—I just put these in to demonstrate the fact that one could do it. I think it would actually be best to back out the YAML files from this PR before merging and land those changes separately, especially to make the release notes more informative.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which is to say, once I've written the guidelines, webcodecs might not get a split at all.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alright, making the actual changes separately sounds good!

We do need to make sure we have a real case for splitting however. If we can only come up with "composite" features that we might later want to merge back together, then I'm not sure we should remove the original feature. Do have features that were combined by mistake and should never be considered one?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, I'm not currently seeing a compulsory split, if we're assuming some future composite feature schema.

It's somewhat easier to find historic cases. #1089 is a case where, without a splitting schema, would produce either a) a breaking release (which is basically what we did, in the pre-1.0 era) or b) a useless composite feature that combines something interoperable and something that never will be. In the latter case, caniuse has a corresponding feature, but I don't think we should follow caniuse's lead there.

There are also cases we've already merged that look a little suspect, where we split something by moving keys, tweaking a description, and just kinda pretending we got it right in the first place (e.g., #2491, #2652). I don't wish to bank on always being on the right side of that line.

Which brings me to my last concern: split ought to be the reverse of merged. If we wish to be able to merge freely, then we'll need a safe undo. Otherwise, merges will have the feeling of a semver-major event for maintainers here, even if it doesn't bump the version number.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's use #2776 as the feature to demonstrating split. We'd split that into gradients (2 BCD keys) and conic-gradients (1 BCD key).

@ddbeck ddbeck added this to the web-features v3.0 milestone May 29, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feature definition Creating or defining new features or groups of features. feature evolution Issues/PRs for describing changing feature definitions over time (as opposed to support) major version required This PR requires a minor version semver release (vX+1.0.0) package:web-features schema Schema changes, proposals, and bugs tools and infrastructure Project internal tooling, such as linters, GitHub Actions, or repo settings
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants