[ci] Render an upstream baseline copy of the spec in proposal repos (#2229)

Proposal repos are plain forks of `WebAssembly/spec`, so their published
webassembly.github.io/<proposal>/ site has no rendered copy of the
unmodified spec to compare against. The proposals often also lag behind
the upstream spec so a direct comparison between the rendered specs is
full of false differences. A reviewer who wants to see what a proposal
actually does to the spec text has to build upstream themselves, or read
source diffs, which is particularly awkward for parts of the spec which
are generated in the output. e.g. typeset rules, tables, appendices, etc.

With this change a fork also renders every document at the commit where
it diverged from its parent repo, and publishes the result under
webassembly.github.io/<proposal>/upstream with the same layout as the
main site. This will allow us to link to W3C's spec diff service and
view a formatted and searchable comparison with a single URL. e.g.

https://services.w3.org/htmldiff?doc1=https://webassembly.github.io/<proposal>/upstream/core/bikeshed/&doc2=https://webassembly.github.io/<proposal>/core/bikeshed/

The baseline is chosen by a new resolve-baseline job, which asks the `gh`
API for the repository's parent, fetches the parent's main, and takes
`git merge-base`. For most proposals which sync by merging upstream,
this resolves to the most recent sync point. When running on
`WebAssembly/spec`, a fork with no changes of its own, or when the
parent cannot be determined / fetched, the job short-circuits and no
upstream copy is generated.

Each build job stages its render at the final path it occupies on the
site. This lets the publish job merge every artifact into one tree
instead of mapping each one to a destination. Adding a document no
longer requires touching the publish job. It feels like this should be
the Makefile's job but I'll leave that to another PR.

The commit upstream was rendered from is recorded at
/upstream/baseline-sha and compared on the next run. When the shas match,
the upstream variant is dropped from the build matrix and the published
copy is carried over instead of being rendered again. This saves a
decent amount of CI time for most (non-downstreaming) commits.
1 file changed
tree: 9b2a53f592a8560abdccf20e65da85de79676994
  1. .github/
  2. document/
  3. interpreter/
  4. papers/
  5. proposals/
  6. specification/
  7. spectec/
  8. test/
  9. .gitattributes
  10. .gitignore
  11. .gitmodules
  12. Contributing.md
  13. LICENSE
  14. README.md
  15. w3c.json
  16. wasm-specs.bib
README.md

Spectec Status Interpreter Status Spec doc Status

CI for specs CI for interpreter & tests

spec

This repository holds the sources for the WebAssembly specification, a reference implementation, and the official test suite.

A formatted version of the spec is available here: webassembly.github.io/spec,

Participation is welcome. Discussions about new features, significant semantic changes, or any specification change likely to generate substantial discussion should take place in the WebAssembly design repository first, so that this spec repository can remain focused. And please follow the guidelines for contributing.

citing

For citing WebAssembly in LaTeX, use this bibtex file.