From 2c78cb8dbbd1269ccd7210187cb3ca0c3de688a9 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Tue, 14 Nov 2023 16:22:41 +0100 Subject: [PATCH 1/6] Add core Baseline definition --- README.md | 2 +- docs/baseline.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+), 1 deletion(-) create mode 100644 docs/baseline.md diff --git a/README.md b/README.md index 570b9c052f..9e4a832a16 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ By creating a common list of features and their definitions, `web-features` aims `web-features` does this by: * Creating feature definitions, which identify and describe capabilities of the web -* Generating _Baseline_ support data, which summarizes the availability of web features across key browsers and releases +* Generating [_Baseline_](./docs/baseline.md) support data, which summarizes the availability of web features across key browsers and releases * Publishing the `web-features` npm package, which bundles feature identifiers with Baseline statuses From `Array` to Cascade Layers to Offscreen Canvas, `web-features` identifies, defines, and categorizes capabilities of the web platform that web developers care about. diff --git a/docs/baseline.md b/docs/baseline.md new file mode 100644 index 0000000000..bb4cc2a6a8 --- /dev/null +++ b/docs/baseline.md @@ -0,0 +1,48 @@ + + +## Status definition + +The status has two substatuses: an interoperable low status and a wider-support high status. +If a feature satisfies the requirements of both substatuses, then the high status takes precedence over the low status. + +### Interoperable (low) status + +This status represents the initial interoperability of a feature across many browsers. +The status marks the starting point for setting the wider support (high) status. +The status provides a versionable date for a feature. + +For each feature definition in `web-features`, an interoperable status shall be assigned to the feature if the feature satisfies all of the following tests: + +1. For each current stable release in the [core browser set](#core-browser-set), the release supports the feature (as reported by the current version of `@mdn/browser-compat-data`, excluding those features identified as having `partial_implementation`). +2. The feature definition does not have a value set indicating that: + + - The specification text contains discouraging language, such as a deprecation notice, obsolescence warning, or legacy tag. + - The governance group is withholding or modifying the status (i.e., there is no editorial override of the feature’s status). + +If the feature has the interoperable status, then the feature’s _keystone date_ shall be set to the last release date on which a browser introduced support for the feature +If there was more than one introduction (e.g., a feature was withdrawn then reintroduced), then only the latest date applies. + +### Wider-support (high) status + +For each feature definition in `web-features`, a wider-support status shall be be conferred to the feature if the feature satisfies the following test: + +The feature’s keystone date is on or before today’s date minus 30 months and the dates of the following long-term support releases: + +* Mozilla Firefox ESR, given by the release date for the latest x.0 release of Firefox ESR (or the previous x.0 release, when there are two active ESR releases). + +This duration is selected to approximate developer signals, estimates of browser release uptake over time, an estimate of high total market share support, and the project governance group’s best judgment. + +This duration is due for review by the governance group on 7 November 2024. + +### Core browser set + +Both the interoperable and wider-support substatuses observe support with respect to a set of browsers. +The _core browser set_ shall be defined as: + +* Apple Safari (iOS) +* Apple Safari (macOS) +* Mozilla Firefox (Android) +* Mozilla Firefox (desktop) +* Google Chrome (Android) +* Google Chrome (desktop) +* Microsoft Edge (desktop) From ed538bb012fec62c27dcecba871f4ce817f0fac3 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Tue, 14 Nov 2023 16:23:01 +0100 Subject: [PATCH 2/6] Add governance amendment companion to the Baseline definition --- GOVERNANCE.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 25c4092b96..70c0732ab6 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -171,6 +171,8 @@ The _Owners_ commit to meeting on a quarterly basis, or more often as needed, on The meeting is run by a designated chair selected by the _Owners_ group. Meetings will typically tend to important or unresolved matters, such as modifications of governance, contribution policy, project membership, or release process. +Reviewing and renewing the [definition of Baseline](./docs/baseline.md) must appear on the agenda of the _Owners_ group meeting at least once per calendar year. + Any community member or _Peer_ can ask that something be added to the next meeting’s agenda by logging a GitHub Issue. _Peers_ can add the item to the agenda by adding the [meeting-agenda](https://github.com/web-platform-dx/feature-set/labels/meeting-agenda) label to the issue and _Contributors_ can ask _Peers_ or _Owners_ to add the label for them (though they’re not obliged to accept the request). From 18cd60e3411171e95c1c7cee7d4ae63de905cf0a Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Wed, 29 Nov 2023 16:47:03 +0100 Subject: [PATCH 3/6] Add introductory text --- docs/baseline.md | 135 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 134 insertions(+), 1 deletion(-) diff --git a/docs/baseline.md b/docs/baseline.md index bb4cc2a6a8..c39b629c9d 100644 --- a/docs/baseline.md +++ b/docs/baseline.md @@ -1,4 +1,123 @@ - +## Baseline + +This document describes what Baseline intends to do and specifies how features are to receive a Baseline status. + +## Background and motivation + +Web developers report that [keeping up with changes to the platform is a major issue for them](https://web.dev/deep-dive-into-developer-pain-points/). +Developers have difficulty keeping up with changes in the web platform, such as the introduction of new features and the resolution of interoperability issues, and knowing when features are well-established in their users’ browsers. + +Historically, a developer could have regarded a single browser, such as Internet Explorer 11, as the least common denominator for browser capabilities in general. +But the advent of so-called “evergreen” browsers has upended that approach. + +Many developers enjoy access to detailed information about their audiences and the browsers they use (e.g., through site analytics, support metrics, user interviews, etc.) but others don’t. +A new project won’t have a measurable audience until it launches. +A library maintainer or application vendor might have, at best, an indirect view of the capabilities of users’ browsers. + +Despite the glut of information about browser support, releases, and global usage, these developers are left on their own to draw a platform-wide support picture, with ample opportunity for errors and confusion. +_Baseline_ (alongside related statuses) is intended to help these developers by offering a shortcut past the complexity. + +## Goals + +_Baseline_ status is a wayfinding tool for web developers. +Baseline status aims to help web developers to identify consensus web platform features and distinguish them from features that are in other states of development (e.g., proposals, experiments, or deprecated and historic features; see also [Future considerations](#future-considerations)). +In other words, Baseline status aims to identify features of developers’ contemporary, workaday web. + +Goal 1: **Tailor Baseline status to a developer audience.** +The Baseline status is intended for developers creating and maintaining hypertext applications for the web, who may not have access to the resources, data, tools, or knowledge needed to identify their users’ browsers capabilities more directly. +See [Audience illustration for Baseline status](#audience-illustration-for-baseline-status) for a detailed story to help understand this goal in more detail. + +Goal 2: **Change with the web and web developers’ needs.** Features can and should join and leave Baseline status as their respective interoperability, reliability, commitment, and availability profiles change. Likewise, Baseline statuses should change as developers’ needs change (for example, developers come to rely on a new browser or an established browser fades from use). Baseline is not an inert, one-time assessment. + +Goal 3: **Identify interoperability through support across browser implementations.** +Baseline features demonstrate consensus through multiple implementations. +Baseline is not for single-implementation browser features. + +Goal 4: **Identify availability through popular browser support.** +Baseline features demonstrate consensus through user reach, a supermajority of global users by reasonable measures used by web developers. +Baseline features should not surprise a web developer with compatibility failures. + +Goal 5: **Identify continuity through support over time.** +Baseline features demonstrate consensus through constancy: uninterrupted support from one release to the next. +Baseline is not for prototypes, betas, or temporary hacks. +All software has bugs, but Baseline features have narrow, known bugs. + +Goal 6: **Identify commitment through documentation.** +Baseline features demonstrate consensus through specifications, documentation for web developers, and other signs that the feature will continue to have a place in a web developer’s toolbox. +Baseline features aren’t unspecified or formally discouraged. + + + +**Issue TBD**: Part of goal 6 ought to be part of feature-set/web-features feature definition rules, not in Baseline status selection. + +## Non-goals + +Baseline status cannot or will not satisfy the following non-goals: + +* **Identify universally available features.** + Many Baseline features will not achieve 100% user reach soon or perhaps ever. + If a web developer needs to support a globally uncommon or discontinued browser (e.g., Internet Explorer 11), then the developer needs to know the specific limitations of that browser, not a broad overview of developers’ most commonly required browsers. + Baseline can’t be both. +* **Identify support in non-web environments.** + Developers use web technologies in non-web settings, such as JavaScript in Node.js, Web APIs in Deno, or HTML and CSS in Electron-based applications. + For good reasons, web technologies in non-web settings often depart from interoperability with web browsers. + Baseline’s ability to report broad consistency would be undermined by accommodating such departures. +* **Tailor Baseline status to standards bodies, browser implementers, and other audiences.** + Baseline is intended to fill a troublesome gap in web developer experience. + Other audiences may find utility in Baseline, but their needs must not come at the expense of developer experience. +* **Identify features that are good candidates for polyfilling or progressive enhancement.** + Baseline features should "just work" when you use them, without requiring polyfills or workarounds. + Instead, developers should be able to use Baseline to decide when to stop shipping a polyfill. + See also: [Future considerations](#future-considerations). +* **Replace fine-grained or site-specific reporting or analyses.** + Baseline is a complement to, not a replacement for, detailed compatibility reporting, such as _Can I Use…?_ or browser compatibility tables on MDN. + Likewise, Baseline is not a substitute for custom analysis (e.g., [Import statistics on Can I Use…?](https://caniuse.com/ciu/import)). + Baseline may aid web developers in directing their browser support investigations but, as a summary, won’t eliminate application-specific analysis. +* **Foreclose on other statuses.** + Baseline’s goals capture a certain kind of stability in web platform features, but that’s far from the only status relevant to web developers. + Other categories could surely exist to complement or work alongside Baseline. + Baseline should seek to summarize underlying facts about web platform features, not canonize them. + See also: [Future considerations](#future-considerations). + +## Audience illustration for Baseline status + + + +**Issue TBD**: This persona will likely have utility for all of feature-set/web-features and should move to some project-wide documentation and get a cross reference here. + +Although Baseline is intended for web developers, “web developers” is an extremely broad category, which includes ranges of experience, goals, and motivations. +It’s hard to make tools for a broad category. +Instead, we can use a more specific example as a proxy for the group as a whole. + +The audience for Baseline status is illustrated through the following story. +This is but one of several possible stories to help keep in mind the needs and constraints of web developers who use Baseline. + +> A web developer is responsible for the maintenance of a static site generator. +> +> The application is typically used in a self-hosted manner: other, downstream web developers download, install, and run the application themselves. +> The downstream developers rarely contribute to the application’s source code or documentation and even less rarely contribute funds for ongoing development. +> But they are generous with bug reports and complaints. +> +> The developer needs to make browser support decisions that work for them, for downstream developers (the site generator users), and for _their_ users (end users). +> The developer wants to maximize backwards compatibility and minimize complaints from downstream developers about browser support issues. +> +> But the developer has several constraints that influence their day-to-day decisions about whether to use a given web platform feature: +> +> * The developer does not have access to downstream developers’ analytics and they don't use telemetry in the application itself, so they can’t directly know anything about end users’ browsers. +> * The developer has limited time and budget to get relatively old or new devices and test with. +> They use a 2-year old laptop that they keep _mostly_ up-to-date with OS and browser updates. +> * The developer has limited time and interest to keep up with browser news. +> They don’t routinely read web development blogs. +> * The developer recently decided to stop worrying about end-of-life browsers. +> +> Today, to decide whether to use a new-to-them web platform feature, the developer uses the same techniques taught by their mentors: skim _Can I use…?_ and MDN browser compatibility tables. +> They mostly work on a gut feeling: is there _enough_ green in the table to use this feature? +> This works some of the time, but they’ve been occasionally surprised by both “new” (and unfamiliar) features being long-supported and unexpected complaints of incompatibility. + +## Ownership and maintenance + +The WebDX community group, through the [web-platform-dx/web-features-set owners group](../GOVERNANCE.md), maintains this document. +Based on WebDX community group research, the feature-set owners group decides matters such as the core browser set, releases, editorial overrides, and so on. ## Status definition @@ -46,3 +165,17 @@ The _core browser set_ shall be defined as: * Google Chrome (Android) * Google Chrome (desktop) * Microsoft Edge (desktop) + +## Future considerations + +There are many things Baseline does not cover. +Here are some areas for future consideration and not currently in-scope for Baseline, particularly other candidate states such as: + + + +* Upcoming (e.g., not yet shipped in all browsers) +* Progressive enhancement safe (i.e., limited penalties for support failures) +* Developer feedback requested +* Buggy (e.g., supported but in ways that are surprising and semi-interoperable) +* Obsolete/deprecated/legacy/etc. (i.e., flagged as such in the specification or dropped from newer versions of the specification) +* Having high-quality polyfills available From 34e4c0b1098a8f26aa8a1be3bffb001f6cd683c9 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Thu, 30 Nov 2023 11:57:17 +0000 Subject: [PATCH 4/6] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Philip Jägenstedt --- GOVERNANCE.md | 2 +- docs/baseline.md | 14 +++++--------- 2 files changed, 6 insertions(+), 10 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 70c0732ab6..76f6841e16 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -174,7 +174,7 @@ Meetings will typically tend to important or unresolved matters, such as modific Reviewing and renewing the [definition of Baseline](./docs/baseline.md) must appear on the agenda of the _Owners_ group meeting at least once per calendar year. Any community member or _Peer_ can ask that something be added to the next meeting’s agenda by logging a GitHub Issue. -_Peers_ can add the item to the agenda by adding the [meeting-agenda](https://github.com/web-platform-dx/feature-set/labels/meeting-agenda) label to the issue and _Contributors_ can ask _Peers_ or _Owners_ to add the label for them (though they’re not obliged to accept the request). +_Peers_ can add the item to the agenda by adding the [meeting-agenda](https://github.com/web-platform-dx/web-features/labels/meeting-agenda) label to the issue and _Contributors_ can ask _Peers_ or _Owners_ to add the label for them (though they’re not obliged to accept the request). The intention of the agenda is not to approve or review all patches. That should happen continuously on GitHub and be handled by the larger group of Peers. diff --git a/docs/baseline.md b/docs/baseline.md index c39b629c9d..ac414304fd 100644 --- a/docs/baseline.md +++ b/docs/baseline.md @@ -46,9 +46,7 @@ Goal 6: **Identify commitment through documentation.** Baseline features demonstrate consensus through specifications, documentation for web developers, and other signs that the feature will continue to have a place in a web developer’s toolbox. Baseline features aren’t unspecified or formally discouraged. - - -**Issue TBD**: Part of goal 6 ought to be part of feature-set/web-features feature definition rules, not in Baseline status selection. + ## Non-goals @@ -81,9 +79,7 @@ Baseline status cannot or will not satisfy the following non-goals: ## Audience illustration for Baseline status - - -**Issue TBD**: This persona will likely have utility for all of feature-set/web-features and should move to some project-wide documentation and get a cross reference here. + Although Baseline is intended for web developers, “web developers” is an extremely broad category, which includes ranges of experience, goals, and motivations. It’s hard to make tools for a broad category. @@ -117,7 +113,7 @@ This is but one of several possible stories to help keep in mind the needs and c ## Ownership and maintenance The WebDX community group, through the [web-platform-dx/web-features-set owners group](../GOVERNANCE.md), maintains this document. -Based on WebDX community group research, the feature-set owners group decides matters such as the core browser set, releases, editorial overrides, and so on. +Based on WebDX community group research, the web-features owners group decides matters such as the core browser set, releases, editorial overrides, and so on. ## Status definition @@ -160,11 +156,11 @@ The _core browser set_ shall be defined as: * Apple Safari (iOS) * Apple Safari (macOS) -* Mozilla Firefox (Android) -* Mozilla Firefox (desktop) * Google Chrome (Android) * Google Chrome (desktop) * Microsoft Edge (desktop) +* Mozilla Firefox (Android) +* Mozilla Firefox (desktop) ## Future considerations From 7fd5f49297a78bbe67b2b36256fb0892ccabc086 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Mon, 4 Dec 2023 18:39:26 +0000 Subject: [PATCH 5/6] Apply editorial suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: François Daoust --- docs/baseline.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/baseline.md b/docs/baseline.md index ac414304fd..b985ecd7bc 100644 --- a/docs/baseline.md +++ b/docs/baseline.md @@ -124,7 +124,7 @@ If a feature satisfies the requirements of both substatuses, then the high statu This status represents the initial interoperability of a feature across many browsers. The status marks the starting point for setting the wider support (high) status. -The status provides a versionable date for a feature. +The status provides a versionable date for a feature, called the _keystone date_. For each feature definition in `web-features`, an interoperable status shall be assigned to the feature if the feature satisfies all of the following tests: @@ -139,7 +139,7 @@ If there was more than one introduction (e.g., a feature was withdrawn then rein ### Wider-support (high) status -For each feature definition in `web-features`, a wider-support status shall be be conferred to the feature if the feature satisfies the following test: +For each feature definition in `web-features`, a wider-support status shall be conferred to the feature if the feature satisfies the following test: The feature’s keystone date is on or before today’s date minus 30 months and the dates of the following long-term support releases: From 14b1c5d98fa354d33ccd4822cf44b4af26572c49 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Tue, 5 Dec 2023 13:01:08 +0000 Subject: [PATCH 6/6] Emphasize stable-ishness of Baseline itself --- docs/baseline.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/baseline.md b/docs/baseline.md index b985ecd7bc..2d28497d68 100644 --- a/docs/baseline.md +++ b/docs/baseline.md @@ -27,7 +27,10 @@ Goal 1: **Tailor Baseline status to a developer audience.** The Baseline status is intended for developers creating and maintaining hypertext applications for the web, who may not have access to the resources, data, tools, or knowledge needed to identify their users’ browsers capabilities more directly. See [Audience illustration for Baseline status](#audience-illustration-for-baseline-status) for a detailed story to help understand this goal in more detail. -Goal 2: **Change with the web and web developers’ needs.** Features can and should join and leave Baseline status as their respective interoperability, reliability, commitment, and availability profiles change. Likewise, Baseline statuses should change as developers’ needs change (for example, developers come to rely on a new browser or an established browser fades from use). Baseline is not an inert, one-time assessment. +Goal 2: **Change with the web and web developers’ needs.** +Features can and should join and leave Baseline status as their respective interoperability, reliability, commitment, and availability profiles change. +Likewise, Baseline statuses should change as developers’ needs change (for example, developers come to rely on a new browser or an established browser fades from use). +Baseline is not an inert, one-time assessment, nor is it arbitrary, changing form from one day to the next. Goal 3: **Identify interoperability through support across browser implementations.** Baseline features demonstrate consensus through multiple implementations.