Add Baseline regression notes #3187
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -47,6 +47,8 @@ export interface FeatureData { | |
| compat_features?: string[]; | ||
| /** Whether developers are formally discouraged from using this feature */ | ||
| discouraged?: Discouraged; | ||
| /** Notes about this feature */ | ||
| notes?: BaselineRegressionNote[]; | ||
|
There was a problem hiding this comment. Do we really need this to be an array? I don't think we do, but I can see the point that not making it an array might, some day, block us, and require a major release to change it then. There was a problem hiding this comment. Good question, @captainbrosset! I think it's very likely that we'll have other note types and notes may need to coexist. My inclination was to introduce one note type, then add more. But I recognize it looks a little odd now because there really ought to be just one note at a time under the constraints presented here. But there's some likely follow up note types: First, consider the mirror of a regression: a case where we've prevented a feature from advancing (think of it as Second, there are cases where we might choose to not regress a feature, like #2957 (though it's still my preference to let it regress). It seems to me it might be wise for us to (publicly) acknowledge the bug, even if we do not believe it enough to regress the feature (something like I imagine there are still further note types (e.g., something like solicitations for input on potentially deprecating or removing a feature, for instance, as in the case of XSLT), but I haven't given them a ton of thought yet. There was a problem hiding this comment. I see. The |
||
| } | ||
|
|
||
| type BrowserIdentifier = "chrome" | "chrome_android" | "edge" | "firefox" | "firefox_android" | "safari" | "safari_ios"; | ||
|
|
@@ -82,6 +84,27 @@ interface Discouraged { | |
| // https://github.com/web-platform-dx/web-features/issues/2722 is resolved. | ||
| } | ||
|
|
||
| /** | ||
| * A note describing a Baseline status regression. | ||
| * For example, a feature that has moved from Baseline low to not Baseline. | ||
| */ | ||
| interface BaselineRegressionNote { | ||
| /** The topic of this note. This field is also a discriminator for any future note types */ | ||
| category: "baseline-regression"; | ||
| /** The date that the regression was added to web-features data */ | ||
| date: string; | ||
| /** A short description of the cause of the regression as a plain text */ | ||
| message: string; | ||
| /** A short description of the cause of the regression as HTML */ | ||
| message_html: string; | ||
| /** One or more URLs, such as bugs, used to justify the regression */ | ||
| citations: string[]; | ||
| /** The `baseline` status value before the regression */ | ||
| old_baseline_value: "high" | "low"; | ||
| /** The `baseline` status value after the regression */ | ||
| new_baseline_value: "low" | false; | ||
| } | ||
|
|
||
| export interface GroupData { | ||
| /** Short name */ | ||
| name: string; | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When I opened this PR, I had written this note. However, the feature has since progressed. It occurred to me that we should not show irrelevant notes, so I commented it out. This is a rather new idea, so I'd like to delete this entirely, if we decide this is the right way to go.
Other options considered: some sort of "historic" flag on notes that are no longer relevant, or filtering historic notes from the published package. I figured both of those added complexity that wouldn't be very useful to anyone, least of all developers.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I almost feel like we should have a linting step in place which checks that
notes.new_baseline_valueis equal tostatus.baseline, and if not, deletes that particular note. I think keeping old notes about status regressions that no longer apply would be confusing. I don't think that web-features necessarily needs to keep track of the history of a feature. Its role is to document the platform as it is now.