# Build resources

The resources in this folder are used for building WHATWG standards.

## `deploy.sh`

The `deploy.sh` script is used by most WHATWG standards and is meant to run either in GitHub Actions to build/deploy, or locally for preview purposes. It performs the following steps:

- Running [Bikeshed](https://github.com/tabatkins/bikeshed), through its [web API](https://api.csswg.org/bikeshed/), to produce:
  - If on the main branch, the built Living Standard, as well as a commit snapshot
  - Otherwise, a branch snapshot of the standard
- Running the [Nu HTML checker](http://checker.html5.org/) on the build results
- Deploying the build results to the WHATWG web server (on push to the main branch, not on pull requests)

For GitHub Actions deploys, the following environment variables are required:
- `$SERVER` is the server to deploy to.
- `$SERVER_PUBLIC_KEY` is the public key of the deploy server, in the format of `known_hosts`.
- `$SERVER_DEPLOY_KEY` is the deploy key for the server, which will be passed to `ssh-add`.

The GitHub Actions workflows for build/deploy are generated by [spec-factory](https://github.com/whatwg/spec-factory) and include these required environment variables.

Optional environment variables:
- `$EXTRA_FILES` are extra files to copy for each build. Shell wildcards are allowed, and directory structure will be preserved. Example: `EXTRA_FILES="images/*.png"`.
- `$POST_BUILD_STEP` is an extra step to run after each build. Evaluated with the `$DIR` variable set to the build directory. Example: `POST_BUILD_STEP='python generate-stuff.py "$DIR"'`.

To cause particular errors or warnings emitted by the HTML checker to be suppressed, add a file named `.htmlcheckerfilter` at the root of the repo for a particular standard, and put filter patterns into it, as documented at https://github.com/validator/validator/wiki/Message-filtering#using-the---filterfile-option.

A local deploy can be performed with

```bash
curl --remote-name --fail https://resources.whatwg.org/build/deploy.sh && bash ./deploy.sh
```

or more typically `make deploy`.

Whether the script is running locally or on GitHub Actions, and whether it should really deploy, is determined using [the `GITHUB_*` environment variables](https://help.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables).