Merge remote-tracking branch 'spec/main' into rebase

Author: Guy Bedford

.github/workflows/ci-interpreter.yml

@@ -3,11 +3,11 @@ name: CI for interpreter & tests
 on:
   push:
     branches: [ main ]
-    paths: [ interpreter/**, test/** ]
+    paths: [ .github/**, interpreter/**, test/** ]
 
   pull_request:
     branches: [ main ]
-    paths: [ interpreter/**, test/** ]
+    paths: [ .github/**, interpreter/**, test/** ]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -23,7 +23,7 @@ jobs:
         with:
           ocaml-compiler: 4.12.x
       - name: Setup OCaml tools
-        run: opam install --yes ocamlbuild.0.14.0 ocamlfind.1.9.5 js_of_ocaml.4.0.0 js_of_ocaml-ppx.4.0.0
+        run: opam install --yes ocamlfind.1.9.5 js_of_ocaml.4.0.0 js_of_ocaml-ppx.4.0.0
       - name: Setup Node.js
         uses: actions/setup-node@v2
         with:

.github/workflows/ci-spec.yml

@@ -3,11 +3,11 @@ name: CI for specs
 on:
   push:
     branches: [ main ]
-    paths: [ document/** ]
+    paths: [ .github/**, document/** ]
 
   pull_request:
     branches: [ main ]
-    paths: [ document/** ]
+    paths: [ .github/**, document/** ]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:

.github/workflows/mirror-to-master.yml

@@ -0,0 +1,18 @@
+name: Mirror main branch to master branch
+
+on:
+  push:
+    branches:
+      - 'main'
+
+jobs:
+  mirror_job:
+    runs-on: ubuntu-latest
+    name: Mirror main branch to master branch
+    steps:
+    - name: Mirror branch
+      uses: google/[email protected]
+      with:
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+        source: 'main'
+        dest: 'master'

.github/workflows/w3c-publish.yml

@@ -0,0 +1,36 @@
+name: Publish to W3C TR space
+
+on:
+  push:
+    branches: [ main ]
+    paths: [ .github/**, document/** ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  publish-to-w3c-TR:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v2
+        with:
+          submodules: "recursive"
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16
+      - name: Setup Bikeshed
+        run: pip install bikeshed && bikeshed update
+      - name: Setup TexLive
+        run: sudo apt-get update -y && sudo apt-get install -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
+      - name: Setup Sphinx
+        run: pip install six && pip install sphinx==5.1.0
+      - name: Publish all specs to their https://www.w3.org/TR/ URLs
+        run: cd document && make -e WD-echidna-CI
+        env:
+          STATUS: --md-status=WD
+          W3C_ECHIDNA_TOKEN_CORE: ${{ secrets.W3C_ECHIDNA_TOKEN_CORE }}
+          W3C_ECHIDNA_TOKEN_JSAPI: ${{ secrets.W3C_ECHIDNA_TOKEN_JSAPI }}
+          W3C_ECHIDNA_TOKEN_WEBAPI: ${{ secrets.W3C_ECHIDNA_TOKEN_WEBAPI }}
+          YARN_ENABLE_IMMUTABLE_INSTALLS: false

Contributing.md

@@ -3,6 +3,6 @@
 Interested in participating? Please follow
 [the same contributing guidelines as the design repository][].
 
-  [the same contributing guidelines as the design repository]: https://github.com/WebAssembly/design/blob/master/Contributing.md
+  [the same contributing guidelines as the design repository]: https://github.com/WebAssembly/design/blob/main/Contributing.md
 
 Also, please be sure to read [the README.md](README.md) for this repository.

README.md

@@ -1,4 +1,5 @@
-![Build Status](https://github.com/WebAssembly/spec/actions/workflows/main.yml/badge.svg)
+[![CI for specs](https://github.com/WebAssembly/spec/actions/workflows/ci-spec.yml/badge.svg)](https://github.com/WebAssembly/spec/actions/workflows/ci-spec.yml)
+[![CI for interpreter & tests](https://github.com/WebAssembly/spec/actions/workflows/ci-interpreter.yml/badge.svg)](https://github.com/WebAssembly/spec/actions/workflows/ci-interpreter.yml)
 
 # ES Module Integration Proposal for WebAssembly
 

document/Makefile

@@ -1,6 +1,7 @@
-DIRS     = core js-api web-api
+DIRS     = js-api web-api core
 FILES    = index.html
 BUILDDIR = _build
+TAR      = tar
 
 # Global targets.
 
@@ -24,6 +25,25 @@ clean: $(DIRS:%=clean-%)
 .PHONY: diff
 diff: $(DIRS:%=diff-%)
 
+# macOS: do “brew install tar” & run “make” as: TAR=gtar make -e WD-tar
+.PHONY: WD-tar
+WD-tar:
+	for dir in $(DIRS); \
+		do STATUS=--md-status=WD TAR=$(TAR) $(MAKE) -e -C $$dir $@;\
+	done
+
+# macOS: do “brew install tar” & run “make” as: TAR=gtar make -e WD-echidna
+.PHONY: WD-echidna
+WD-echidna:
+	for dir in $(DIRS); \
+		do $(MAKE) -e -C $$dir $@;\
+	done
+
+.PHONY: WD-echidna-CI
+WD-echidna-CI:
+	for dir in $(DIRS); \
+		do $(MAKE) -e -C $$dir $@;\
+	done
 
 # Directory-specific targets.
 

document/README.md

@@ -3,9 +3,9 @@
 This directory contains the source code for the WebAssembly spec documents, as served from the [webassembly.github.io/spec](https://webassembly.github.io/spec) pages.
 It uses [Sphinx](http://www.sphinx-doc.org/) and [Bikeshed](https://github.com/tabatkins/bikeshed).
 
-To install Sphinx:
+To install Sphinx (and required library six):
 ```
-pip install sphinx
+pip install sphinx six
 ```
 
 To install Bikeshed, see the instructions [here](https://tabatkins.github.io/bikeshed/#installing).
@@ -42,7 +42,7 @@ pipenv shell
 Install Python dependencies:
 
 ```
-pipenv install Sphinx==3.5.2
+pipenv install Sphinx==4.0.0 six
 ```
 
 ### Checking out the repository

document/core/Makefile

@@ -9,6 +9,8 @@ BUILDDIR      = _build
 STATICDIR     = _static
 DOWNLOADDIR   = _download
 NAME          = WebAssembly
+DECISION_URL  = https://github.com/WebAssembly/meetings/blob/main/main/2017/WG-12-06.md
+TAR           = tar
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -89,12 +91,14 @@ bikeshed-keep:
 	  echo Downloaded Bikeshed.
 
 
-.PHONY: index
-index:
-	(cd appendix; ./gen-index-instructions.py)
+GENERATED = appendix/index-instructions.rst
+.INTERMEDIATE: $(GENERATED)
+
+%.rst: %.py
+	(cd `dirname $@`; ./`basename $^`)
 
 .PHONY: pdf
-pdf:	index latexpdf
+pdf:	$(GENERATED) latexpdf
 	mkdir -p $(BUILDDIR)/html/$(DOWNLOADDIR)
 	ln -f $(BUILDDIR)/latex/$(NAME).pdf $(BUILDDIR)/html/$(DOWNLOADDIR)/$(NAME).pdf
 
@@ -103,9 +107,10 @@ pdf:	index latexpdf
 clean:
 	rm -rf $(BUILDDIR)
 	rm -rf $(STATICDIR)
+	rm -f $(GENERATED)
 
 .PHONY: html
-html: index
+html: $(GENERATED)
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	for file in `ls $(BUILDDIR)/html/*.html`; \
 	do \
@@ -121,28 +126,34 @@ html: index
 	@echo "Build finished. The HTML pages are in `pwd`/$(BUILDDIR)/html/."
 
 .PHONY: dirhtml
-dirhtml:
+dirhtml: $(GENERATED)
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
 .PHONY: singlehtml
-singlehtml:
+singlehtml: $(GENERATED)
 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
 .PHONY: bikeshed
-bikeshed:
+bikeshed: $(GENERATED)
 	$(SPHINXBUILD) -b singlehtml -c util/bikeshed \
 		$(ALLSPHINXOPTS) $(BUILDDIR)/bikeshed_singlehtml
-	python util/bikeshed_fixup.py $(BUILDDIR)/bikeshed_singlehtml/index.html \
+	python3 util/bikeshed_fixup.py $(BUILDDIR)/bikeshed_singlehtml/index.html \
 		>$(BUILDDIR)/bikeshed_singlehtml/index_fixed.html
+	@echo ==== Showing contents of _build/bikeshed_singlehtml/index_fixed.html ====
+	@head -n10 _build/bikeshed_singlehtml/index_fixed.html
+	@echo ... skipping $$(expr `cat _build/bikeshed_singlehtml/index_fixed.html | wc -l` - 20) lines ...
+	@tail -n10 _build/bikeshed_singlehtml/index_fixed.html
+	@echo
+	@echo =========================================================================
 	mkdir -p $(BUILDDIR)/bikeshed_mathjax/
-	bikeshed spec index.bs $(BUILDDIR)/bikeshed_mathjax/index.html
+	bikeshed spec $(STATUS) index.bs $(BUILDDIR)/bikeshed_mathjax/index.html
 	mkdir -p $(BUILDDIR)/html/bikeshed/
 	(cd util/katex/ && yarn && yarn build && npm install --only=prod)
-	python util/mathjax2katex.py $(BUILDDIR)/bikeshed_mathjax/index.html \
+	python3 util/mathjax2katex.py $(BUILDDIR)/bikeshed_mathjax/index.html \
 		>$(BUILDDIR)/html/bikeshed/index.html
 	mkdir -p $(BUILDDIR)/html/bikeshed/katex/dist/
 	cp -r util/katex/dist/* $(BUILDDIR)/html/bikeshed/katex/dist/
@@ -154,9 +165,11 @@ bikeshed:
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/html/bikeshed/."
 
 .PHONY: WD-tar
+# macOS tar has no “--transform” option (only GNU tar does), so on macOS,
+# do “brew install tar” & run “make” like this: “TAR=gtar make -e WD-tar”
 WD-tar: bikeshed
 	@echo "Building tar file..."
-	tar cvf \
+	$(TAR) cvf \
 		$(BUILDDIR)/WD.tar \
 		--transform='s|$(BUILDDIR)/html/bikeshed/||' \
 		--transform='s|index.html|Overview.html|' \
@@ -181,6 +194,20 @@ WD-echidna: WD-tar
 	@echo
 	@echo "Published working draft. Check its status at https://labs.w3.org/echidna/api/status?id=`cat $(BUILDDIR)/WD-echidna-id.txt`"
 
+.PHONY: WD-echidna-CI
+WD-echidna-CI: WD-tar
+	@if [ -z $(W3C_ECHIDNA_TOKEN_CORE) ] || \
+			[ -z $(DECISION_URL) ] ; then \
+		echo "Must provide W3C_ECHIDNA_TOKEN_CORE and DECISION_URL environment variables"; \
+		exit 1; \
+	fi
+	curl 'https://labs.w3.org/echidna/api/request' \
+		-F "tar=@$(BUILDDIR)/WD.tar" \
+		-F "token=$(W3C_ECHIDNA_TOKEN_CORE)" \
+		-F "decision=$(DECISION_URL)" | tee $(BUILDDIR)/WD-echidna-id.txt
+	@echo
+	@echo "Published working draft. Check its status at https://labs.w3.org/echidna/api/status?id=`cat $(BUILDDIR)/WD-echidna-id.txt`"
+
 .PHONY: diff
 diff: bikeshed
 	@echo "Downloading the old single-file html spec..."
@@ -259,7 +286,7 @@ latex:
 	      "(use \`make latexpdf' here to do that automatically)."
 
 .PHONY: latexpdf
-latexpdf:
+latexpdf: $(GENERATED)
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
 	$(MAKE) -C $(BUILDDIR)/latex LATEXMKOPTS=" </dev/null" all-pdf >$(BUILDDIR)/latex/LOG 2>&1 || cat $(BUILDDIR)/latex/LOG