Automatic Publishing of W3C Technical Reports

Goals of automatic publishing

/TR should represent the web we want.

In order to keep it up-to-date, we need to reduce the gap with the editor's draft and faciliate the updates to /TR.

The automatic publication system: Echidna

Echidna can process a document and publish to /TR if:

• it can download all the resources to be published
• the document passes pubrules
• the transition has been approved (CR Snapshots only)
• all the resources are located in the same directory or a known area

Current applicability

• Limited to WDs, CR Snapshots, CR Drafts and Notes
• Echidna cannot process:
  • documents switching WGs
  • specification shortname changes
  • CRs returning to WDs

Requirements...

• Your specification in a GitHub repository
• A link to the WG decision to use Echidna. This link is required only for archival purposes
• A token (one per specification), provided by your team contact or chair, to authenticate the request
• Admin rights on the repository

... for CR Snapshots

• Transition request as a w3c/transition issue (templates of pre-filled issues linked from README.md)
• Issue title MUST end with the specification shortname
• Draft transition announcement sent to w3t-comm
• W3C Director and Communication team MUST respectively comment on the issue "Transition approved." and "Draft transition approved."

Examples: issue #199 and issue #261

Set up your repo for automatic TR updates

To get started with Echidna, we recommend using the GitHub action spec-prod written by Sid Vishnoi.

spec-prod can:

• generate snapshots from ReSpec and Bikeshed source documents (for compound documents, the relevant assets will also be downloaded before publishing)
• validate documents (markup, CSS, hyperlinks)
• publish snapshots to GitHub Pages and/or to /TR via Echidna

Token as a repository secret (1/2)

The token provided by the team contact should be added to your repository as a repository secret.

Token as a repository secret (2/2)

---

spec-prod workflow

# .github/workflows/pr-push.yml
name: CI
on:
  pull_request: {}
  push:
    branches: [main]
jobs:
  main:
    name: Build, Validate and Deploy
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2
      - uses: w3c/spec-prod@v2
        with:
          W3C_ECHIDNA_TOKEN: ${{ secrets.W3C_TR_TOKEN }}
          W3C_WG_DECISION_URL: <DECISION>
        

By default, spec-prod will look for source files index.html (ReSpec) or index.bs (Bikeshed).

Customize the workflow

spec-prod offers a few options to customize the build, such as:

• TOOLCHAIN: to specify the processor ('respec' or 'bikeshed')
• SOURCE: to use a source document other than index.html/index.bs
• VALIDATE_LINKS: by default, spec-prod checks for broken links. Set to false if you want to skip that step
• VALIDATE_MARKUP: same as VALIDATE_LINKS but for markup/CSS
• W3C_BUILD_OVERRIDE: options to override the bikeshed/respec configuration
• W3C_NOTIFICATIONS_CC: Comma separated list of email addresses to get the results of the request

Example of customized workflow

# .github/workflows/echidna-publishing.yml
name: CI
on:
  push:
    branches: [main]
jobs:
  main:
    name: Build, Validate and Deploy
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2
      - uses: w3c/spec-prod@v2
        with:
          W3C_ECHIDNA_TOKEN: ${{ secrets.W3C_TR_TOKEN }}
          TOOLCHAIN: bikeshed
          SOURCE: foobar.bs
          W3C_NOTIFICATIONS_CC: echidna@example.org
          W3C_WG_DECISION_URL: https://lists.w3.org/Archives/Public/...
          W3C_BUILD_OVERRIDE: |
             shortname: spec-1
             status: WD
        

Other examples of workflows

More examples of configurations are listed in examples.md

Check results (1/2)

The status of the workflow can be found in the 'Actions' tab, e.g. mediacapture-record:

Check results (2/2)

spec-prod will check the result of the request to Echidna a few times only. If the request is still pending when the workflow completes, the report will be sent to public-tr-notifications once it's over.

Overview

Alternatives to spec-prod

Although spec-prod is the recommended way to publish /TR document with Echidna, there are other methods described in the wiki.

Get help!

• irc: #pub
• GitHub: Echidna, spec-prod
• email: webreq

What's next?

• remove some limitations (specification ownership changes, CR/CRS returning to WD, ...)
• "Revising a W3C Recommendation" per process document 2020