Skip to content

How to use Echidna with ReSpec and GitHub

Jump to bottom
Denis Ah-Kang edited this page Mar 5, 2019 · 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 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)! See this page for what you actually need to do.

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/%3FspecStatus%3DWD%26shortName%3DtheShortName

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

    • url=: the URL to your echidna config on GitHub. Note: provide the URL of the actual manifest, not the GitHub HTML view of it. Example: Use https://w3c.github.io/YourSpecName/ECHIDNA rather than https://github.com/w3c/YourSpecName/ECHIDNA
    • decision=: URL to the working group decision on a w3c mailing list.
    • token= the token you got from the W3C.
    • editorial=: optional parameter only used for CR updates. It specifies if the new CR has editorial changes only or if there are substantive changes, thus requiring a new director's approval and call for exclusion → true if it's editorial only (default value `false).

    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