web-features

The web-features project provides a curated list of web platform features and explores the set of interoperable features of the web platform. Use the following resources to navigate the project:

• Contributing: Learn how to contribute to the project via Contributing to the web-features project.
• Feature Writing: Follow the Feature guidelines for instructions on how to write and define new features.
• Review & Management: See Pull request and issue management for guidelines on reviewing and merging changes.
• Baseline Status: For information regarding what Baseline is and the logic used to calculate Baseline status, refer to the Baseline documentation.

Baseline is a wayfinding tool for web developers designed to identify consensus web platform features. It helps distinguish established, workaday features from those that are still in development (proposals, experiments) or are deprecated/historic.

Baseline aims to provide a shortcut for developers to understand feature availability without needing to perform deep, site-specific browser compatibility analysis. It focuses on features that demonstrate:

• Interoperability: Support across multiple browser implementations.
• Availability: Support across a supermajority of global users.
• Continuity: Uninterrupted support from one release to the next.
• Commitment: Presence in official specifications and documentation.

The project uses a consensus-seeking decision-making model. The goal is to achieve true consensus before resorting to a vote.

Decision Process:

1. Consensus Seeking: Participants discuss the agenda item to reach agreement.
2. Final Call: When consensus appears reached, the chair asks, "Does anyone object?" to check for final dissent.
3. Voting (if consensus fails): If consensus cannot be reached, an Owner may call for a closing vote or a vote to defer the issue to the next meeting. A call for a vote must be approved by a majority of Owners.
4. Outcome: A simple majority wins.
5. Memorialization: All collective decisions made by Owners must be memorialized in writing (e.g., in a document, PR comment, or issue).

Overrides should be used sparingly. Preferred alternatives include splitting a feature into multiple features or fixing upstream data. Use overrides only in these specific scenarios:

• Reconsideration: To prevent a status from advancing or regressing while a feature is under review.
• Missing Data: To set a status when no relevant BCD keys exist.
• Data Errors: To override BCD when data is suspected to be incorrect (consider filing an upstream issue first).
• Caniuse Alignment: To align with caniuse support information, especially for features predating web-features.
• Birthday Setting: To set the original version or date when an established feature acquired minor behavioral additions or restrictions (rare).

The web-features and mdn/browser-compat-data (BCD) repositories are complementary. They synchronize feature mappings using two primary methods: tagging keys in BCD or listing keys in web-features source YAML files.

• Tagging in BCD: BCD keys are tagged with web-features:<feature-id>. This is preferred for small, incremental changes.
• Listing in web-features: Keys are explicitly listed in the compat_features field of a feature's source YAML file in web-features. These are later migrated to BCD tags via an automated process.

Key Rule for Maintainers: To avoid circular dependencies, BCD contributors should not create a tag for an ID that does not yet exist in web-features. Conversely, web-features contributors should not manually remove compat_features lists from source files.

Some feature IDs in the features object act as redirects to ensure data integrity when features change.

Moved Features (kind: "moved")

Treat these like an HTTP 301 redirect. Use the redirect_target property to find the new feature ID.

{
  "kind": "moved",
  "redirect_target": "new_feature_id"
}

Split Features (kind: "split")

These act like a Wikipedia disambiguation page. Use the redirect_targets array to present the user with multiple relevant feature options.

{
  "kind": "split",
  "redirect_targets": ["feature_a", "feature_b"]
}

Proposed features follow a specific lifecycle to transition from early discovery to official publication:

1. Creation: A .yml file is created in the features/draft/proposed/ directory containing metadata like an explainer or spec URL and a chromestatus URL.
2. Transition: A maintainer creates the official feature entry and updates the proposed feature file to act as a pointer.
3. Redirection: The proposed feature file is updated with a kind: moved status and a redirect_target pointing to the new feature ID.
4. Update: Consumers update their references from the proposed/ ID to the final feature ID.

In this project, a feature is an individual component of the web platform used by developers to achieve specific tasks. A feature has no fixed size and can range from a single CSS property to an entire JavaScript API (like fetch()) or a combination of HTML, CSS, and JS (like the Web Audio API).

When deciding if a new item should be a distinct feature, consider:

• Developer Recognition: Do developers discuss it as a standalone entity in blogs, Stack Overflow, or social media?
• Existing Publications: Is it described as a feature in Can I Use, CSS-Tricks, DEV.to, or MDN?
• Expectation: For new features, use the specification process (e.g., TC39 proposals vs. CSS specs) to make an educated guess.

The proposed/ prefix is reserved for features that have not yet been officially published in web-features. You can refer to these early-stage features using the proposed/a-feature notation in your tools or source code.

Once a feature is officially published, the proposed ID may be updated to a redirect_target. You should eventually update your references from the proposed ID to the final, published feature ID.

proposed/html-pis