Support for non-browser specs

[tidoust]

This issue tracks the extension of the browser-specs to cover non-browser specs.

The browser-specs was created to track specs that target Web browsers. Once in a while, selection criteria are a bit fuzzy but list boundaries have remained relatively clear so far and have shown value for integration in tools and projects such as Webref, MDN, WPT.

Now, some tools actually need to ingest more than just "browser" specs. Notably, spec authoring tools would happily extend their cross-referencing (xref) terms database so that other specs may benefit from it as well. For instance, a given WoT spec may need to reference a WoT term defined in another WoT spec. Currently, it cannot rely on the xref mechanism for that.

We already had to add a few specs to browser-specs that don't meet selection criteria, e.g. the Process and Patent Policy specs. This somewhat works but can break expectations from tools that rely on browser-specs to stick to actual browser specs, see #390 (comment)

Introducing other specs may create other side effects. For instance, the WoT Scripting API defines WebIDL that is not implemented in browsers and should not be included in the @webref/idl package.

It seems useful to have a way to open up browser-specs to non-browser specs. It should equally be easy to get back to a browser-only list of specs. We could perhaps maintain two lists of specs in the browser-specs repo. Or perhaps keep one list and flag non-browser specs somehow.

[tidoust]

Reopening as "fixes" reference in merged PR was wrong...

[foolip]

Could such specs go in a separate package, and ideally a separate repo?

[tidoust]

That is one option. We still don't really have a clear view of what we want to end up with in practice and it affects more than just the browser-specs repo. There will be scenarios where people will want to merge the lists and scenarios they will want to consider lists separately. In the xref example, goal is probably to end up with only one database, currently at Webref. In the WoT example, we would want the IDL to be separated from the rest of the IDL.

We may end up duplicating browser-specs and webref, but that introduces a bit of maintenance overhead and will impact some of the tools as well.

[foolip]

I think it's a wonderful feature of browser-specs that it only includes things that are implemented in some browser. It would be great if the browser-specs keeps being that, it's in the name after all.

If this repo is renamed all-the-specs and only a subset ends up in the browser-specs package, that would be fine for my usage.

[tidoust]

Quick summary: Goal is to expand the list of specs to non-browser specs and release the new list as an npm package named web-specs, while keeping the browser-specs npm package intact.

Reffy would then depend on web-specs and crawl the whole list. Webref would need to be slightly updated to filter out non browser specs when it prepares the curated versions of the idlnames and idlnamesparsed folders and the @webref/xxx packages.

To achieve this, I propose to:

1. Add a new categories property (any better name?) in the description of a spec, which lists categories that the spec belongs to. Initially, there would only be one value: "browser" that identifies specs targeted at browsers. More categories can be introduced over time as needed (no need to specify the taxonomy now). It may be possible to compute the "browser" tag for most specs automatically, e.g. based on the group or organization responsible for them (typically, we already maintain a list of groups that do not target browsers in data/ignore.json).
2. Create the same release workflow as in Webref and semi-automate the release of npm packages through pre-release PRs that present the diff to release. There would be two packages to start with: web-specs, which would contain the whole list, and browser-specs, which would continue to contain specs targeted at browsers. More packages could be introduced over time if needed. Most of the job logic used in Webref to create a similar workflow can be reused with only minor tweaks. We'll just need to automate minor version bumps (instead of a patch bump) whenever the list of specs has changed.

One good thing about introducing such a workflow is that it will also make validation of the diff an explicit step of the release process. That is something that I do manually looking at the history of commits before I hit the release button, and it is sometimes useful to spot problems that tests cannot cover (such as weird spec titles).

A more concrete list of todos:

• Update index.json

  • Add new categories property (array of strings), with only one category initially: "browser"
  • Adjust schema accordingly

• Update build-index.js

  • Compute the categories property, probably based on a list of groups that do not target browsers by default taken from data/ignore.json

• Update specs.json

  • Add "categories" property where needed (when it cannot be computed automatically)
  • Adjust schema accordingly

• Update build.yml job

  • Run tests after build and before commit. Fail job before commit when tests fail.
  • Add logic to bump minor version when the list of specs has changed.
  • Prepare pre-release PRs for web-specs and browser-specs after commit. Same logic as in webref. This includes adding a packages folder with two sub-folders web-specs and browser-specs and the right package.json and README.md files within these folders.

• Add release-package.yml job

  • Same logic as in Webref.

Once we have something in place, we may consider renaming the repository if that feels needed.

[foolip]

@tidoust that sounds good, and means I can keep using browser-specs in the way I have so far.

[tidoust]

Plan suggested above has now been implemented. There may remain bugs as the whole release workflow has not yet run for real (coz' server issues right now) but I'll address them as they appear.

In short:

• Specs are now tagged with a categories property, which can only contain "browser" for now.
• A new web-specs package got released. It contains all the specs. Right now, that means the exact same list as in the last version of the browser-specs package, but the latter should soon become a subset of the former.
• NPM packages reviews and releases are now handled through pull requests, created automatically.
• The web-specs@latest branch is now the one published under GitHub Pages. It contains the index.json file at the time when the latest version of the web-specs package was released.
• A browser-specs@latest branch also exists that points at the commit on the main branch that triggered the release of the latest version of the browser-specs package. Note that, as opposed to the index.json file in the browser-specs package, which only contains specs that target browsers, the index.json file in that branch is the full list (and thus non-browser specs need to be filtered out if one is only interested in specs that target browsers).

New non-browser specs have not yet been added to the list. Let's make sure that everything works as planned first ;)

[foolip]

A browser-specs@latest branch also exists that points at the commit on the main branch that triggered the release of the latest version of the browser-specs package. Note that, as opposed to the index.json file in the browser-specs package, which only contains specs that target browsers, the index.json file in that branch is the full list (and thus non-browser specs need to be filtered out if one is only interested in specs that target browsers).

@tidoust I'm not sure I follow. Will a new browser-specs package be released which excludes https://www.w3.org/Consortium/Patent-Policy/? Will that be a major version bump? This is what I'd like to see, but then I'm not sure if I need to do anything about filtering as a user of browser-specs, or if that's only if I've checked out the branch in the repo?

[tidoust]

Will a new browser-specs package be released which excludes https://www.w3.org/Consortium/Patent-Policy/?

Yes.

Will that be a major version bump?

I was more thinking of a minor version bump. From a browser-specs package perspective, this will just remove a handful of specs (Patent Policy, Process document, i18n glossary), which we usually qualify as a minor update.

This is what I'd like to see, but then I'm not sure if I need to do anything about filtering as a user of browser-specs, or if that's only if I've checked out the branch in the repo?

That's only I you decided to check out the browser-specs@latest branch in the repo. The browser-specs NPM package that you'll get will contain the filtered list already, so you won't need to filter anything.

[foolip]

Alright, sounds good! I don't really care about semver, so whatever version component you'd like to bump is fine with me :)