Skip to content

How to use Echidna with ReSpec and GitHub

Jump to bottom
Denis Ah-Kang edited this page Sep 29, 2015 · 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.

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 Token

You will need to get a token for your spec from the W3C. You can request the token while you are waiting for WG consensus through the CFC (see above)!

What you actually need to do:

  1. Find your team contact and cc the WG chair(s) on your requests so everyone is aware and in sync.
  2. In the email, say you want an Echidna Token for your spec (and a link to your spec).
  3. include the URL to the Call for Consensus (CFC) to publish the spec using the new publication process.

If you have multiple specs you want to publish, feel free to batch them in the same email.

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

Welcome back! now that you have all the things above, you can finally proceed to publishing.

  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/?specStatus=WD;shortName=theShortName

  5. Ok! now run the following using curl. You will need:

    • url=: the URL to your echidna config on GitHub, as served from GitHub pages (usually http://w3c.github.io/YourSpecName/ECHIDNA).
    • decision=: URL to the working group decision on a w3c mailing list.
    • token= the token you got from the W3C.

    Got 'em? Good! now replace all the bits below...

    curl 'https://labs.w3.org/echidna/api/request' --data 'url=<echidnaConfigURL>&decision=<decisionUrlOnMailingList>&token=<W3Ctoken>

    Finally, once you do that, you can check if your document actually got published by going to the TR-Notification list. If something went wrong, it will tell you what happened (and hopefully what you need to fix!).

    Otherwise, you should see success! If successful, your Working Draft should now be on /TR/.

Clone this wiki locally