Re: New publication workflow: Echidna 1.1.1 and Specberus 1.0.3 released

With some help from Dom, I finally managed to get this working with GitHub and ReSpec. 

I've written some notes on how to actually get Echidna to work (below). I've also asked that the following be added to Echidna's wiki:

Hopefully, this will make it easier for people to actually make use of Echidna (I spent about a month scratching my head before Dom walked me through it in about 10 minutes - the instructions on the Echidna project page are not targeted at actual users of Echidna yet, so they don't make a lot of sense if you are trying to use Echidna as an end-user/Editor).
/
Hope this helps! Please feel free to improve by adding additional comments to this bug (the Echidna Wiki is locked, it seems?):
https://github.com/w3c/echidna/issues/127


=====

# How to use Echidna with ReSpec and GitHub

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

You will need the following:

 1. Working Group Approval to use the new process. 
 1. A token from the W3C. 
 1. 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 to do so by your Working Group by emailing your group's mailing list. See, for example, how [approval was requested for the WebApps WG](https://lists.w3.org/Archives/Public/public-webapps/2014JulSep/0627.html)

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 your 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 this while you are waiting for WG consensus through the CFC (see above)! Email either your team contact or webreq@w3.org.

You will get an email within a few days with your token. 

## 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](https://www.w3.org/users/myprofile):

<image with arrows to where the ID is>

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

```JS
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. Follow the [Echinda clone and installation steps](https://github.com/w3c/echidna/#echidna). 
1. Go to the root directory where your spec is and make a config file for your spec. Call it ECHIDNA.

```BASH 
touch ECHIDNA
```

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

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

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

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

1 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

1. 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... 

```BASH
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](https://lists.w3.org/Archives/Public/public-tr-notifications/). 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/.






On March 17, 2015 at 6:45:15 AM, Antonio Olmo Titos (antonio@w3.org) wrote:
>  
> Hello, everyone
>  
> Today we deployed new versions of our tools for automated publishing:
> Echidna (the publication API) and Specberus (the pubrules checker). This
> fresh release just processed and published the latest WD for HTML 5.1 [1].
>  
> We are now managing versions better -- tagging releases in Git and
> showing those versions clearly in the front-end. Also, both Echidna and
> Specberus live under labs.w3.org now, with nicer URLs.
>  
> • Echidna 1.1.1 → https://labs.w3.org/echidna/
> • Specberus 1.0.3 → https://labs.w3.org/pubrules/
>  
> Let me summarise some of the changes in the system since the initial
> release, a month ago:
>  
> • Enforcing that a WD's date must be "today".
> • Added automatic detection of manifest; removed parameter
> "isManifest".
> • Added an option in the Specberus form to check a WD
> *specifically* for publication with Echidna.
> • Updated rules for copyright boilerplate according to latest changes.
> • Refactored UI messages, allowing for easier l10n and more verbose
> error messages (in progress).
> • Additions and fixes to documentation in the wiki [2], and to the
> readme [3].
> • Better integration of sub-projects in Echidna as Node.js modules [4].
> • Measuring code coverage now [5, 6].
> • Specberus now published as an npm package [7].
> • Bugfixing!! Echidna: 9 issues closed [8] and 22 PRs merged [9].
> Specberus: 5 issues closed [10] and 13 PRs merged [11].
>  
> There are still lots of things to polish here and there, but we think we
> are in the right track! I'm looking forward to a more robust system,
> with better error messages and a simple web interface that may help some
> users to invoke the API...
>  
> While we get there, I appreciate your patience with these initial
> releases... and your feedback :)
>  
> [1]
> https://lists.w3.org/Archives/Public/public-tr-notifications/2015Mar/0003.html  
> [2] https://github.com/w3c/echidna/wiki
> [3] https://github.com/w3c/echidna/blob/master/README.md
> [4] https://github.com/w3c/echidna/blob/master/package.json#L45
> [5] https://coveralls.io/r/w3c/echidna
> [6] https://coveralls.io/r/w3c/specberus
> [7] https://www.npmjs.com/package/specberus
> [8]
> https://github.com/w3c/echidna/issues?q=is%3Aissue+closed%3A%3E2015-02-06T14%3A00%3A00%2B09%3A00  
> [9]
> https://github.com/w3c/echidna/pulls?q=is%3Apr+merged%3A%3E2015-02-06T14%3A00%3A00%2B09%3A00  
> [10]
> https://github.com/w3c/specberus/issues?q=is%3Aissue+closed%3A%3E2015-02-06T14%3A00%3A00%2B09%3A00  
> [11]
> https://github.com/w3c/specberus/pulls?q=is%3Apr+merged%3A%3E2015-02-06T14%3A00%3A00%2B09%3A00  
>  
> --
> Antonio Olmo Titos
> web developer, W3C
> antonio@w3.org
> http://w3.org/People/Antonio
> +81 335162504
>  
>  
>

Received on Tuesday, 17 March 2015 18:34:39 UTC