[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.
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.
For citing WebAssembly in LaTeX, use this bibtex file.