[ci] Render an upstream baseline copy of the spec in proposal repos

[kmiller68]

Proposal repos are plain forks of WebAssembly/spec, so their published webassembly.github.io// 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//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//upstream/core/bikeshed/&doc2=https://webassembly.github.io//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.

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.

[kmiller68]

For help with reviewing here are two CI runs:

• https://github.com/kmiller68/spec/actions/runs/31828913256 a run with no baseline upstream
• https://github.com/kmiller68/spec/actions/runs/31829903826 a run with baseline upstream matching so no-rebuild

Published output from the two current runs:

• https://kmiller68.github.io/spec/ and https://kmiller68.github.io/spec/upstream/
• https://github.com/kmiller68/spec/blob/gh-pages/upstream/baseline-sha — bdd7164
• The diff, two markers apart: https://services.w3.org/htmldiff?doc1=https%3A%2F%2Fkmiller68.github.io%2Fspec%2Fupstream%2Fcore%2Fbikeshed%2F&doc2=https%3A%2F%2Fkmiller68.github.io%2Fspec%2Fcore%2Fbikeshed%2F (may take about ~10-20s to load)

After writing this I also realized that gh-pages is actually a git repo itself. So in theory there are historical renderings from the merge-base. That said, there are a few reasons I uploaded this anyway:

1. https://raw.githubusercontent.com/WebAssembly/spec/dbde29a3e/js-api/index.html is served as text rather than html and services.w3.org won't process it.
2. Historical builds of the spec could have different versions of rendering tools.
3. Not every commit deploys so champions would have to find the most recent deployment when downstreaming.

[kmiller68]

One other decision I made is to use FETCH_HEAD rather than hardcoding WebAssembly/spec as the upstream source. For most proposals these are the same but for ones dependent on another proposal they might depend on a different proposal. e.g. shared everything, which depends on threads (I assume anyway). I'm open to hardcoding WebAssembly/spec if folks think that's a better choice though.

[kmiller68]

@rossberg @tlively Do either of you want to review this? it seems like you two have touch this file the most recently.

[tlively]

Nice! I will definitely use this.

[tlively]

Can we avoid listing out all these directories so we can't accidentally forget to add new directories in the future?

[tlively]

https://github.com/kmiller68/spec/actions/runs/31828913256/job/94859702501 logs "base64: invalid input" here. Is that expected?