1212 # Allows you to run this workflow manually from the Actions tab
1313 workflow_dispatch :
1414
15+ permissions :
16+ contents : read
17+
18+ # Path within the published site recording the commit the baseline was rendered
19+ # from, both as provenance and so a run can tell the copy is still current.
20+ env :
21+ BASELINE_STAMP : upstream/baseline-sha
22+
1523jobs :
1624 ensure-wasm-latest :
17- if : ${{ github.repository == 'WebAssembly/spec' }}
1825 runs-on : ubuntu-latest
1926 steps :
2027 - name : Checkout repo
2128 uses : actions/checkout@v4
2229 - name : Diff wasm-latest
30+ if : ${{ github.repository == 'WebAssembly/spec' }}
2331 run : cd specification && bash diff-wasm-latest.sh
2432
33+ # Forks (i.e. proposal repos) also render the spec at the commit where they
34+ # last diverged from their parent repo, so the proposal can be compared
35+ # against an unmodified baseline. That baseline is published under /upstream.
36+ resolve-baseline :
37+ runs-on : ubuntu-latest
38+ outputs :
39+ variants : ${{ steps.resolve.outputs.variants }}
40+ # The commit the baseline is rendered from, empty when there is none. A
41+ # baseline absent from variants is one already published under /upstream.
42+ base-sha : ${{ steps.resolve.outputs.base-sha }}
43+ steps :
44+ - name : Checkout repo
45+ uses : actions/checkout@v4
46+ with :
47+ # merge-base needs the full history
48+ fetch-depth : 0
49+ - name : Resolve upstream baseline
50+ id : resolve
51+ env :
52+ GH_TOKEN : ${{ secrets.GITHUB_TOKEN }}
53+ REPOSITORY : ${{ github.repository }}
54+ run : |
55+ set -euo pipefail
56+ # Written once on whichever path exits below, so these defaults stand
57+ # unless the checks further down replace them.
58+ variants='["head"]'
59+ base=''
60+ write_outputs() {
61+ echo "variants=$variants" >> "$GITHUB_OUTPUT"
62+ echo "base-sha=$base" >> "$GITHUB_OUTPUT"
63+ }
64+ trap write_outputs EXIT
65+ if [ "$REPOSITORY" = "WebAssembly/spec" ]; then
66+ echo "Canonical repo, no upstream baseline."
67+ exit 0
68+ fi
69+ # A copy already on the site is left in place unless a newer baseline
70+ # is rendered below.
71+ published=''
72+ if encoded=$(gh api "repos/$REPOSITORY/contents/$BASELINE_STAMP?ref=gh-pages" --jq .content 2>/dev/null); then
73+ published=$(printf '%s' "$encoded" | base64 -d | tr -d '[:space:]')
74+ fi
75+ parent=$(gh api "repos/$REPOSITORY" --jq '.parent.full_name // ""' 2>/dev/null) || parent=''
76+ if [ -z "$parent" ]; then
77+ echo "::warning::Could not determine the parent repo, not rendering an upstream copy."
78+ exit 0
79+ fi
80+ if ! git fetch --no-tags --quiet "https://github.com/$parent.git" main; then
81+ echo "::warning::Could not fetch $parent, not rendering an upstream copy."
82+ exit 0
83+ fi
84+ if ! merge_base=$(git merge-base HEAD FETCH_HEAD); then
85+ echo "::warning::No common ancestor with $parent, no upstream copy."
86+ exit 0
87+ fi
88+ if [ "$merge_base" = "$(git rev-parse HEAD)" ]; then
89+ echo "::notice::No divergence from $parent, no upstream copy."
90+ exit 0
91+ fi
92+ base=$merge_base
93+ if [ "$base" = "$published" ]; then
94+ echo "::notice::Baseline $base is already published, keeping that copy."
95+ exit 0
96+ fi
97+ echo "Upstream baseline: $base (from $parent)"
98+ variants='["head","upstream"]'
99+
25100 build-core-spec :
26101 runs-on : ubuntu-latest
102+ needs : resolve-baseline
103+ strategy :
104+ fail-fast : false
105+ matrix :
106+ variant : ${{ fromJSON(needs.resolve-baseline.outputs.variants) }}
27107 steps :
28108 - name : Checkout repo
29109 uses : actions/checkout@v4
30110 with :
31111 submodules : " recursive"
112+ ref : ${{ matrix.variant == 'upstream' && needs.resolve-baseline.outputs.base-sha || '' }}
32113 - name : Setup OCaml
33114 uses : ocaml/setup-ocaml@v3
34115 with :
@@ -51,110 +132,167 @@ jobs:
51132 run : cd document/core && opam exec make main
52133 - name : Run Bikeshed
53134 run : cd document/core && opam exec make bikeshed
135+ - name : Stage artifact at its path on the site
136+ run : mkdir -p _site && mv document/core/_build/html _site/core
54137 - name : Upload artifact
55138 uses : actions/upload-artifact@v4
56139 with :
57- name : core-rendered
58- path : document/core/_build/html
140+ name : core-rendered-${{ matrix.variant }}
141+ path : _site
59142
60143 build-js-api-spec :
61144 runs-on : ubuntu-latest
145+ needs : resolve-baseline
146+ strategy :
147+ fail-fast : false
148+ matrix :
149+ variant : ${{ fromJSON(needs.resolve-baseline.outputs.variants) }}
62150 steps :
63151 - name : Checkout repo
64152 uses : actions/checkout@v4
153+ with :
154+ ref : ${{ matrix.variant == 'upstream' && needs.resolve-baseline.outputs.base-sha || '' }}
65155 - name : Setup Bikeshed
66156 run : pip install bikeshed && bikeshed update
67157 - name : Run Bikeshed
68158 run : bikeshed spec "document/js-api/index.bs" "document/js-api/index.html"
159+ - name : Stage artifact at its path on the site
160+ run : mkdir -p _site/js-api && mv document/js-api/index.html _site/js-api/
69161 - name : Upload artifact
70162 uses : actions/upload-artifact@v4
71163 with :
72- name : js-api-rendered
73- path : document/js-api/index.html
164+ name : js-api-rendered-${{ matrix.variant }}
165+ path : _site
74166
75167 build-web-api-spec :
76168 runs-on : ubuntu-latest
169+ needs : resolve-baseline
170+ strategy :
171+ fail-fast : false
172+ matrix :
173+ variant : ${{ fromJSON(needs.resolve-baseline.outputs.variants) }}
77174 steps :
78175 - name : Checkout repo
79176 uses : actions/checkout@v4
177+ with :
178+ ref : ${{ matrix.variant == 'upstream' && needs.resolve-baseline.outputs.base-sha || '' }}
80179 - name : Setup Bikeshed
81180 run : pip install bikeshed && bikeshed update
82181 - name : Run Bikeshed
83182 run : bikeshed spec "document/web-api/index.bs" "document/web-api/index.html"
183+ - name : Stage artifact at its path on the site
184+ run : mkdir -p _site/web-api && mv document/web-api/index.html _site/web-api/
84185 - name : Upload artifact
85186 uses : actions/upload-artifact@v4
86187 with :
87- name : web-api-rendered
88- path : document/web-api/index.html
188+ name : web-api-rendered-${{ matrix.variant }}
189+ path : _site
89190
90191 build-code-metadata-spec :
91192 runs-on : ubuntu-latest
193+ needs : resolve-baseline
194+ strategy :
195+ fail-fast : false
196+ matrix :
197+ variant : ${{ fromJSON(needs.resolve-baseline.outputs.variants) }}
92198 steps :
93199 - name : Checkout repo
94200 uses : actions/checkout@v4
95201 with :
96202 submodules : " recursive"
203+ ref : ${{ matrix.variant == 'upstream' && needs.resolve-baseline.outputs.base-sha || '' }}
97204 - name : Setup TexLive
98205 run : sudo apt-get update -y && sudo apt-get install -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
99206 - name : Setup Sphinx
100207 run : pip install six && pip install sphinx==8.1.3
101208 - name : Build main spec
102209 run : cd document/metadata/code && make main
210+ - name : Stage artifact at its path on the site
211+ run : mkdir -p _site/metadata && mv document/metadata/code/_build/html _site/metadata/code
103212 - name : Upload artifact
104213 uses : actions/upload-artifact@v4
105214 with :
106- name : code-metadata-rendered
107- path : document/metadata/code/_build/html
215+ name : code-metadata-rendered-${{ matrix.variant }}
216+ path : _site
108217
109218 build-legacy-exceptions-core-spec :
110219 runs-on : ubuntu-latest
220+ needs : resolve-baseline
221+ strategy :
222+ fail-fast : false
223+ matrix :
224+ variant : ${{ fromJSON(needs.resolve-baseline.outputs.variants) }}
111225 steps :
112226 - name : Checkout repo
113227 uses : actions/checkout@v4
114228 with :
115229 submodules : " recursive"
230+ ref : ${{ matrix.variant == 'upstream' && needs.resolve-baseline.outputs.base-sha || '' }}
116231 - name : Setup TexLive
117232 run : sudo apt-get update -y && sudo apt-get install -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
118233 - name : Setup Sphinx
119234 run : pip install six && pip install sphinx==8.1.3
120235 - name : Build main spec
121236 run : cd document/legacy/exceptions/core && make main
237+ - name : Stage artifact at its path on the site
238+ run : mkdir -p _site/legacy/exceptions && mv document/legacy/exceptions/core/_build/html _site/legacy/exceptions/core
122239 - name : Upload artifact
123240 uses : actions/upload-artifact@v4
124241 with :
125- name : legacy-exceptions-core-rendered
126- path : document/legacy/exceptions/core/_build/html
242+ name : legacy-exceptions-core-rendered-${{ matrix.variant }}
243+ path : _site
127244
128245 build-legacy-exceptions-js-api-spec :
129246 runs-on : ubuntu-latest
247+ needs : resolve-baseline
248+ strategy :
249+ fail-fast : false
250+ matrix :
251+ variant : ${{ fromJSON(needs.resolve-baseline.outputs.variants) }}
130252 steps :
131253 - name : Checkout repo
132254 uses : actions/checkout@v4
255+ with :
256+ ref : ${{ matrix.variant == 'upstream' && needs.resolve-baseline.outputs.base-sha || '' }}
133257 - name : Setup Bikeshed
134258 run : pip install bikeshed && bikeshed update
135259 - name : Run Bikeshed
136260 run : bikeshed spec "document/legacy/exceptions/js-api/index.bs" "document/legacy/exceptions/js-api/index.html"
261+ - name : Stage artifact at its path on the site
262+ run : mkdir -p _site/legacy/exceptions/js-api && mv document/legacy/exceptions/js-api/index.html _site/legacy/exceptions/js-api/
137263 - name : Upload artifact
138264 uses : actions/upload-artifact@v4
139265 with :
140- name : legacy-exceptions-js-api-rendered
141- path : document/legacy/exceptions/js-api/index.html
266+ name : legacy-exceptions-js-api-rendered-${{ matrix.variant }}
267+ path : _site
142268
143269 build-spec-versions :
144270 runs-on : ubuntu-latest
271+ needs : resolve-baseline
272+ strategy :
273+ fail-fast : false
274+ matrix :
275+ variant : ${{ fromJSON(needs.resolve-baseline.outputs.variants) }}
145276 steps :
146277 - name : Checkout repo
147278 uses : actions/checkout@v4
279+ with :
280+ ref : ${{ matrix.variant == 'upstream' && needs.resolve-baseline.outputs.base-sha || '' }}
281+ - name : Stage artifact at its path on the site
282+ run : mkdir -p _site && mv document/versions _site/versions
148283 - name : Upload artifacts
149284 uses : actions/upload-artifact@v4
150285 with :
151- name : versions-rendered
152- path : document/versions/
286+ name : versions-rendered-${{ matrix.variant }}
287+ path : _site
153288
154289 publish-spec :
155290 runs-on : ubuntu-latest
291+ permissions :
292+ contents : write
156293 needs :
157294 - ensure-wasm-latest
295+ - resolve-baseline
158296 - build-core-spec
159297 - build-js-api-spec
160298 - build-web-api-spec
@@ -165,43 +303,40 @@ jobs:
165303 steps :
166304 - name : Checkout repo
167305 uses : actions/checkout@v4
306+ with :
307+ # The baseline's index.html is read out of the history below
308+ fetch-depth : 0
168309 - name : Create output directory
169310 run : mkdir _output && cp document/index.html _output/index.html
170- - name : Download core spec artifact
171- uses : actions/download-artifact@v4
172- with :
173- name : core-rendered
174- path : _output/core
175- - name : Download JS API spec artifact
176- uses : actions/download-artifact@v4
177- with :
178- name : js-api-rendered
179- path : _output/js-api
180- - name : Download Web API spec artifact
181- uses : actions/download-artifact@v4
182- with :
183- name : web-api-rendered
184- path : _output/web-api
185- - name : Download code metadata spec artifact
186- uses : actions/download-artifact@v4
187- with :
188- name : code-metadata-rendered
189- path : _output/metadata/code
190- - name : Download legacy exceptions core spec artifact
191- uses : actions/download-artifact@v4
192- with :
193- name : legacy-exceptions-core-rendered
194- path : _output/legacy/exceptions/core
195- - name : Download legacy exceptions JS API spec artifact
311+ - name : Download rendered documents
196312 uses : actions/download-artifact@v4
197313 with :
198- name : legacy-exceptions-js-api-rendered
199- path : _output/legacy/exceptions/js-api
200- - name : Download spec versions artifacts
314+ pattern : ' *-rendered-head'
315+ merge-multiple : true
316+ path : _output
317+ - name : Download upstream baseline documents
318+ if : contains(fromJSON(needs.resolve-baseline.outputs.variants), 'upstream')
201319 uses : actions/download-artifact@v4
202320 with :
203- name : versions-rendered
204- path : _output/versions
321+ pattern : ' *-rendered-upstream'
322+ merge-multiple : true
323+ path : _output/upstream
324+ - name : Record the upstream baseline
325+ if : contains(fromJSON(needs.resolve-baseline.outputs.variants), 'upstream')
326+ env :
327+ BASE_SHA : ${{ needs.resolve-baseline.outputs.base-sha }}
328+ run : |
329+ set -euo pipefail
330+ git show "$BASE_SHA:document/index.html" > _output/upstream/index.html
331+ echo "$BASE_SHA" > "_output/$BASELINE_STAMP"
332+ - name : Keep the upstream baseline copy already published
333+ if : needs.resolve-baseline.outputs.base-sha != '' && !contains(fromJSON(needs.resolve-baseline.outputs.variants), 'upstream')
334+ run : |
335+ set -euo pipefail
336+ # Publishing replaces the whole site, so the copy has to be carried
337+ # over explicitly rather than just left in place.
338+ git fetch --no-tags --depth 1 origin gh-pages
339+ git archive FETCH_HEAD upstream | tar -x -C _output
205340 - name : Publish to GitHub Pages
206341 if : github.ref == 'refs/heads/main'
207342 uses : peaceiris/actions-gh-pages@v4
0 commit comments