Skip to content

How to use Echidna

Jump to bottom
Denis Ah-Kang edited this page Sep 28, 2023 · 50 revisions

Preferred method: spec-prod

We recommend the use of the GitHub Action spec-prod that takes care of:

  • 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

What do you need to make spec-prod publish your specification to /TR?

To get started with spec-prod, you need:

Once all the requirements are met, you can create the GitHub workflow and pass the right parameters to spec-prod.

The example below shows how to generate a WD with the shortname my-custom-shortname from a ReSpec document (foobar.html) using the token ECHIDNA_TOKEN (as a repository secret)

# Example: Override respecConfig for W3C deployment and validators.
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:
          TOOLCHAIN: respec
          SOURCE: foobar.html
          W3C_ECHIDNA_TOKEN: ${{ secrets.ECHIDNA_TOKEN }}
          W3C_WG_DECISION_URL: https://www.example.com
          W3C_BUILD_OVERRIDE: |
            specStatus: WD
            shortName: my-custom-shortname

More examples of how to use spec-prod can be found here and the options are listed here.

Manual methods

If you don't want to rely on spec-prod or you want to trigger requests to Echidna yourself, there are alternatives that are described below.

Check your document using Specberus

Make sure your document passes Specberus with the Echidna option and WD, CR, CRD or WG-NOTE profile. If your document is a non REC-track document, check the option "Rec-track status, but document is not really on Rec-track."

Group decision

Every publication needs to point to the Working Group decision to publish, per the 2015 Process: "must record the group's decision to request publication. Consensus is not required, as this is a procedural step".

Request a publication

The publication system works using UTC (GMT/Zulu)-time. As such, the date of your document MUST match the UTC date.

Two options are available to send a request to Echidna. You can either submit a URL/manifest or a TAR file. Depending on the environment the request is submitted from (CI or not), the authentication method varies:

token (CI only) W3C credentials
URL/manifest ✔ ✘
tar ✔ ✔

URL or manifest

This method is only available in a continuous integration context (GitHub Actions).

You first need to get a token associated with a specification. Ask your team contact to generate a token for your specification.

Once you have your token, you can configure your repository to trigger the request after each commit.

In the CI logs, the POST will return a unique identifier you can use to get the status of the request.

TAR file

You can also send a TAR file directly to Echidna. Its contents will be extracted on the server (read more):

Command to run if you are using your W3C credentials to authenticate:

curl 'https://labs.w3.org/echidna/api/request' --user '<username>:<password>' -F "tar=@/some/path/spec.tar" -F "decision=<decisionUrl>"

or with the token (only works from a GitHub Action):

curl 'https://labs.w3.org/echidna/api/request' -F "tar=@/some/path/spec.tar" -F "token=<token>" -F "decision=<decisionUrl>"

Note:

  1. If you are authenticating with the W3C credentials, Echidna will check that you are participating in the group delivering the specification.
  2. Please make sure you're not using "curl --anyauth" in command nor config --anyauth in your CURL client.

Like the previous method, the POST will return a unique identifier if the request has been correctly authenticated.

Optional parameters

The following parameters are optional to the POST:

  • cc: send notifications to other email addresses, e.g. cc=foo@bar.com,foo1@bar1.com
  • annotation: annotate a request to help identify the document submitted, e.g. annotation=html

Result of the request

Email notification

After a request has been processed, an email is sent to public-tr-notifications@w3.org with the result of the publication. Check the mailing list archive.

/api/status

Another way to check the status of the request is to query /api/status with the unique identifier returned by the POST:

GET http://labs.w3.org/echidna/api/status?id=<id>

Rehearse publication (“dry run”)

Set the optional argument dry-run to 'true' (case-insensitive string) to rehearse publication of a document, avoiding noise in public-tr-notifications/ and not publishing it actually.

curl 'https://labs.w3.org/echidna/api/request' --data 'url=<URL>&decision=<DEC>&token=<TOK>' -d 'dry-run=true'

With a dry run, the document is not published, and no e-mail notification is sent: the only way to check results is then via the status method of the API.

Current limitations

  • only Candidate Recommendations (Snapshots and Drafts), Recommendations with candidate amendments, ordinary Working Drafts, Notes and Draft Registries
  • previous version must be a FPWD, CR, REC, WD, Note or DRY
  • only documents using the HTML5 format (no HTML4 or XHTML 1 documents)
  • no change of WG or shortname
  • for CR Snapshots publications, a transition request can be used for one and only one CR. Indeed, Echidna processes a document one by one and after a CR is published, it closes the transition request issue, which then cannot be reused for other documents
Clone this wiki locally