Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for non-browser specs #496

Merged
merged 7 commits into from
Feb 8, 2022
Merged

Add support for non-browser specs #496

merged 7 commits into from
Feb 8, 2022

Conversation

tidoust
Copy link
Member

@tidoust tidoust commented Feb 7, 2022

This addresses #436.

This update brings a number of changes to the preparation and release of browser-specs as an NPM package in order to support extending the list of specs to also contain specs that are not targeted at browsers.

A new categories property was added to the description of specs. It contains a list of categories that the spec belongs to. The only category so far is "browser" for specs that target web browsers. That category is automatically computed based on the name of the group that develops the spec for now. Explicit info in specs.json may be used to override the computed value.

The code reuses the list of groups and repos in src/data/ignore.json to identify specs that do not target web browsers for the time being. That list should get split into two lists on a short term basis: a list of groups and repos that find-specs.js should indeed ignore, and a list of groups and repos linked to specs that are not targeted at browsers (we won't ignore them anymore, but we won't flag them with a "browser" category). That split is not done in this update. In general, I expect the logic in compute-categories.js to evolve based on non-browser specs that we add to the list.

The release workflow is a copy-and-paste from the one used in webref:

  • A new packages folder contains the list of packages that can be released. Two packages: web-specs which contains all the specs, and browser-specs which contains all specs that target Web browsers.
  • A prepare-packages.js script prepares the contents of these packages.
  • A bump-packages-minor.js script bumps the minor version of these packages whenever a new spec gets added to the package or when a spec gets removed.
  • A prepare-release.js script prepares a pre-release PR per package that contains the diff to release (the actual PR is a patch bump on the package version)
  • A release-package.js script actually releases the packages to NPM when the pre-release PR gets merged.

Jobs were adjusted accordingly. In particular, the build job now only commits updates provided that tests pass, so as not to end up with a committed list that we know is wrong. It also creates the pre-release PRs as needed.

The release job tags the released commit on the main branch, and updates the web-specs@latest and browser-specs@latest branches. The web-specs@latest is the one intended to be published to GitHub Pages.

Notes:

  • The packages READMEs are automatically completed based on the main README.
  • We will lose the changelog and the creation of Git releases with the new release mechanism, but the changelog was full of opaque "Data updated" in any case, so that does not seem to be a big deal.
  • It could be interesting to avoid duplication of common scripts between browser-specs and webref. The scripts are sufficiently similar that this seems worth pursuing, and sufficiently different to make it a bit painful. Plus I'm not too crazy about having to create yet another repo for hosting that common glue code. I propose to address that later on.

Things to do before the PR may be merged:

  • Create a first version of the web-specs npm package
  • Add the npm token secret
  • Create the web-specs@latest and browser-specs@latest branches
  • Switch to web-specs in Reffy (otherwise we'll lose specs such as the W3C Patent Policy or the i18n glossary from Webref)

Things to do before we add further non-browser specs to the list:

  • Add filtering code in Webref curation and release jobs

This update brings a number of changes to the preparation and release of
browser-specs as an NPM package in order to support extending the list of specs
to also contain specs that are not targeted at browsers.

A new `categories` property was added to the description of specs. It contains
a list of categories that the spec belongs to. The only category so far is
`"browser"` for specs that target web browsers. That category is automatically
computed based on the name of the group that develops the spec for now. Explicit
info in `specs.json` may be used to override the computed value.

The code reuses the list of groups and repos in `src/data/ignore.json` to
identify specs that do not target web browsers for the time being. That list
should get split into two lists on a short term basis: a list of groups and
repos that `find-specs.js` should indeed ignore, and a list of groups and repos
linked to specs that are not targeted at browsers (we won't ignore them anymore,
but we won't flag them with a `"browser"` category). That split is not done in
this update. In general, I expect the logic in `compute-categories.js` to evolve
based on non-browser specs that we add to the list.

The release workflow is a copy-and-paste from the one used in webref:
- A new `packages` folder contains the list of packages that can be released.
Two packages: `web-specs` which contains all the specs, and `browser-specs`
which contains all specs that target Web browsers.
- A `prepare-packages.js` script prepares the contents of these packages.
- A `bump-packages-minor.js` script bumps the minor version of these packages
whenever a new spec gets added to the package or when a spec gets removed.
- A `prepare-release.js` script prepares a pre-release PR per package that
contains the diff to release (the actual PR is a patch bump on the package
version)
- A `release-package.js` script actually releases the packages to NPM when the
pre-release PR gets merged.

Jobs were adjusted accordingly. In particular, the build job now only commits
updates provided that tests pass, so as not to end up with a committed list that
we know is wrong. It also creates the pre-release PRs as needed.

The release job tags the released commit on the main branch, and updates the
`web-specs@latest` and `browser-specs@latest` branches. The `web-specs@latest`
is the one intended to be published to GitHub Pages.

Note the packages READMEs are automatically completed based on the main README.

It could be interesting to further general common scripts between browser-specs
and webref. The scripts are sufficiently similar that this seems worth pursuing,
and sufficiently different that this makes is a bit painful. Plus I'm not too
crazy about having to create yet another repo for hosting that common glue code.
I propose to address that later on.

This addresses #436.
.github/workflows/request-pr-review.yml Outdated Show resolved Hide resolved
packages/web-specs/package.json Outdated Show resolved Hide resolved
src/compute-categories.js Show resolved Hide resolved
src/data/ignore.json Outdated Show resolved Hide resolved
@dontcallmedom
Copy link
Member

kudos again on a giant piece of work!

tidoust and others added 3 commits February 8, 2022 11:07
Co-authored-by: Dominique Hazael-Massieux <dom@w3.org>
The i18n glossary spec is rather flagged as non-browser in specs.json
Markdown does not seem to like it when a comment is followed by text on the
same line...
The versions in the `package.json` files now represent the version that will
be published.
@tidoust
Copy link
Member Author

tidoust commented Feb 8, 2022

OK, I wouldn't be surprised if we end up needing to fix a few things in the jobs here and there, but I'll give it a shot ;)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants