Skip to content

How to use Echidna with ReSpec and GitHub

Jump to bottom
Denis Ah-Kang edited this page Feb 1, 2021 · 17 revisions

YOU DON'T NEED TO ACTUALLY INSTALL ECHIDNA AT ALL!

Before you start - unfortunately, there are a few process things you need to do. These steps can take about 1-2 weeks to complete. Note however that you need to do that only once.

You will need the following:

  1. Working Group Approval to use the new process.
  2. A token from the W3C.
  3. The "editor ID" of each editor of the spec.

If you are updating a CR, you need to know if the update contains substantives changes or not.

Working Group Approval

In order to publish your document using the new process, you need to get consensus in your Working Group. You get this by emailing your group's mailing list. See, for example, how approval was requested for the WebApps WG.

The chair will generally put out a Call for Consensus (CFC), which can take about 1 week.

Once you get approval (or the CFC), keep the URL handy 'cause you will need it later to actually publish!

The Editor IDs

Then you will need to get the IDs for the Editors of your spec. You can find yours by going to your W3C profile:

You will need to add this ID to your ReSpec config using the w3cid property, like so:

editors: [{
    name: "Spec Editor",
    w3cid: 39125
}]

Actually publishing

using travis-ci or GitHub Actions

If you want to submit a request to Echidna after each commit, you can configure travis-ci or Github Actions to take care of it.

You will need to get a token for your spec from the W3C team. See this page for what you actually need to do. You will also need to create a manifest:

  1. Go to the root directory where your spec is and make a config file for your spec. It can take the name you want. As an example, let's call it ECHIDNA.

    touch ECHIDNA

  2. In ECHIDNA, you need to list the main spec file and any dependent images or other files. For example:

    # ECHIDNA configuration
index.html?specStatus=WD&shortName=appmanifest respec
images/manifest-src-directive.svg

  3. Save it, and push that back to your gh-pages branch on GitHub.

    git checkout gh-pages
git add ECHIDNA
git commit -m "Echidna config" ECHIDNA
git push

  4. Run your spec over the new PubRules and fix all the errors. PubRules won't accept a raw ReSpec document, so you can basically modify the following to suit your document:

    https://labs.w3.org/spec-generator/?type=respec&url=https://w3c.github.io/linkToYourSpec/%3FspecStatus%3DWD%26shortName%3DtheShortName

Once you are sure your document passes pubrules, you are ready to configure the CI of your repository.

by submitting a tar

If you don't want to rely on travis-ci or GitHub Actions, you can use the tar method to publish to Echidna. You will first need to prepare a tar of your specification (including all the resources needed). Note, that you will need to submit your document to spec-generator first as Echidna will not know how to deal with a respec source document with the tar method.

Once you have the tar ready, you can submit it with the following command:

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

Clone this wiki locally