Skip to content

Commit

Permalink
Only curate specs that have a good standing (#1023)
Browse files Browse the repository at this point in the history
This leverages the `standing` property in browser-specs to exclude specs that
don't have a good standing from data curation.

This makes it possible to add specs to browser-specs at an earlier level for
cross-referencing purpose (Specref and terms) without having to worry too much
about its impact on CSS, elements, events, and IDL definitions. It also makes it
possible to keep discontinued specs in browser-specs without having to worry
about extracts becoming obsolete, invalid, or conflictual.

This is intended to replace #712 with a different exclusion logic. In #712,
specs that were excluded from data curation were the ones that did not target
browsers, based on the `categories` property. This does not help with the main
source of CSS, events and IDL hiccups, which are more common in early API
proposals. Plus I still think that filtering specs based on their categories is
not the right approach.

This will remove the following curated extracts:
- CSS extract of CSS Conditional Values Module Level 1
- CSS extract of Non-element Selectors Module Level 1
- IDL extract of Direct Sockets API. If we want to keep the IDL, the right
mechanism would be to drop the "pending" standing, but the spec itself says that
it is an unofficial draft.
- IDL extract of Web Publications, which seems a good thing given that the spec
has been discontinued.
- IDL extract of Document Object Model (DOM) Level 2 Style, which we were
previously doing through a patch.

This does not add any mechanism to create exceptions to the rule. That is on
purpose. Let's be optimistic ;)

Note the plan to also make Reffy skip "discontinued" specs by default, in
w3c/reffy#1341. With these two updates, the workflow
becomes:
1. Specs that are in good standing are crawled and curated
2. Specs that have a pending standing are crawled but not curated
3. Specs that have been discontinued are not crawled by default (but may be for
legacy/cross-referencing purpose) and not curated.

The rule for inclusion in NPM packages does not change: only specs targeted at
browsers are included.
  • Loading branch information
tidoust authored Aug 1, 2023
1 parent a28d588 commit d75760f
Show file tree
Hide file tree
Showing 3 changed files with 41 additions and 1,357 deletions.
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

This repository contains **machine-readable references of CSS properties, definitions, IDL, and other useful terms that can be automatically extracted from web browser specifications**. The contents of the repository are updated automatically **every 6 hours** (although note information about published _[/TR/](https://www.w3.org/TR/)_ versions of specifications are updated only once per day).

Specifications covered by this repository are technical Web specifications that are directly implemented or that will be implemented by Web browsers; in other words, those that appear in [browser-specs](https://github.com/w3c/browser-specs).
Specifications covered by this repository are technical Web specifications that appear in [browser-specs](https://github.com/w3c/browser-specs).

The `main` branch of this repository contains **automatically-generated raw extracts** from web browser specifications. These extracts come with no guarantee on validity or consistency. For instance, if a specification defines invalid IDL snippets or uses an unknown IDL type, the corresponding IDL extract in this repository will be invalid as well.

Expand All @@ -16,6 +16,8 @@ Additionally, subsets of the curated content get manually reviewed and published
- [`@webref/elements`](https://www.npmjs.com/package/@webref/elements) contains a [curated](packages/elements#guarantees) version of the [`ed/elements`](ed/elements) folder.
- [`@webref/events`](https://www.npmjs.com/package/@webref/events) contains a [curated](packages/events#guarantees) version of the [`ed/events`](ed/events) folder.

**Important:** The curated extracts only contain data for specifications that are in [good standing](https://github.com/w3c/browser-specs/#standing) (to keep the number of manually-maintained patches minimal and manageable). The NPM packages only contain curated extracts of specifications that are in good standing and that [target web browsers](https://github.com/w3c/browser-specs/#categories).

**Important:** Unless you are ready to deal with invalid content, we strongly recommend that you process contents of the `curated` branch or NPM packages instead of raw content in the `main` branch.


Expand Down
Loading

0 comments on commit d75760f

Please sign in to comment.