PR Preview

Increasingly, GitHub is being used to collaborate on documents that aren't just code.

When such documents include a build step, it is often difficult to assess the impact of a pull request by just looking at the source changes.

This is where PR Preview steps in.

PR Preview uses web services to build a ReSpec or Bikeshed versions of the spec in the pull request, which it stores on AWS.

It then uses this spec preview to create an HTML diff of the spec (using yet another web service) which also gets stored on AWS.

Finally, PR Preview conveniently links both preview and HTML diff from within the pull request itself:

This makes it a lot easier to understnad the actual impact of pull requests on the end document, considerably speeds-up pull request reviews, and makes the whole collaboration process more accessible and inclusive.

Assumptions

The only assumption made by PR Preview is that you're using the latest version of either Bikeshed or ReSpec, or vanilla HTML to edit your spec.

Known issues

ReSpec is known to have race condition issues when it's included using the async attribute. Instead, use the defer attribute like so:

<script src="https://www.w3.org/Tools/respec/respec-w3c-common" class="remove" defer></script>

Install

This is available as a GitHub App.

Once the integration is installed, you must add a configuration file to the root of your repository. Nothing will happen until you do.

Note that the following orgs have blanket install of pr-preview, which means that adding a config file is all you need to be setup if your repository is hosted in one of them:

• github.com/w3c
• github.com/whatwg
• github.com/wicg
• github.com/w3ctag

Configuration file

To test your own config file and turn it into a pull request, go to the config page.

You must configure PR Preview by adding a .pr-preview.json json file at the root of your repository with the following fields:

{
    "src_file": "index.bs",
    "type": "bikeshed",
    "params": {
        "md-foo": "bar"
    }
}

src_file (required)

This should point to the relative path to the source file from the root of the repository.

type (required)

One of "bikeshed", "respec", or "html".

params (optional)

params are used to construct the URL that transform the source file into an html document using either:

• Bikeshed's web service, or
• W3C's ReSpec web service.

When constructing the URL, params are rendered as if they were mustache template strings. You can also use an array of strings, instead of a string, to pass multiple values for the same query parameter.

They're passed an object containing the config object itself, the pull_request payload and the owner, repo, branch, sha, short_sha and url of the branch being rendered:

{
    config: { /* ... */ },       // The config object defined above.
    pull_request: { /* ... */ }, // The pull request payload.
    owner: "heycam",             // owner's login
    repo: "webidl",              // repo's name
    branch: "gh-pages",          // branch name
    sha: "7dfd134ee2e6df7fe...", // duh
    short_sha: "7dfd134",        // sha truncated to 7 characters
    url: "https://s3.amazon..."  // URL where the spec will be hosted
}

Here's a fairly involved config file example the URL standard could use to produce this snapshot:

{
    "src_file": "url.bs",
    "type": "bikeshed",
    "params": {
        "force": 1,
        "md-status": "LS-COMMIT",
        "md-h1": "URL <small>(<a href=\"{{ pull_request.html_url }}\">PR #{{ pull_request.number }}</a>)</small>",
        "md-warning": "Commit {{ short_sha }} {{ pull_request.head.repo.html_url }}/commit/{{ sha }} replaced by {{ config.ls_url }}",
        "md-title": "{{ config.title }} (Pull Request Snapshot #{{ pull_request.number }})",
        "md-Text-Macro": ["SNAPSHOT-LINK {{ config.back_to_ls_link }}", "COMMIT-SHA {{ sha }}"]
    },
    "ls_url": "https://url.spec.whatwg.org/",
    "title": "URL Standard",
    "back_to_ls_link": "<a href=\"https://url.spec.whatwg.org/\" id=\"commit-snapshot-link\">Go to the living standard</a>"
}

post_processing (optional)

This let's you opt into post-processing. For example, to use the emu-algify post-processor:

{
    "src_file": "index.bs",
    "type": "bikeshed",
    "params": {
        "md-foo": "bar"
    },
    "post_processing": {
        "name": "emu-algify",
        "options": {
            "throwingIndicators": true
        }
    }
}

post_processing.name

Lets you choose the post-processor. Currently, the only supported ones are "emu-algify" and "webidl-grammar".

post_processing.options (optional)

Used to pass an options object to the post-processor.

Hosting generously provided by UnlockOpen.