New publication workflow: Echidna 1.1.1 and Specberus 1.0.3 released

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

New publication workflow: Echidna 1.1.1 and Specberus 1.0.3 released

Antonio Olmo Titos

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
  [hidden email]
  http://w3.org/People/Antonio
  +81 335162504


Reply | Threaded
Open this post in threaded view
|

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

Marcos Caceres-4
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 [hidden email].

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 ([hidden email]) 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
> [hidden email]
> http://w3.org/People/Antonio
> +81 335162504
>  
>  
>  


Reply | Threaded
Open this post in threaded view
|

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

Marcos Caceres-4
Important note: you don't need to install Echidna at all to use it as an Editor... please ignore that step in my notes usage notes. 



On March 17, 2015 at 2:34:11 PM, Marcos Caceres ([hidden email]) wrote:

> 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 [hidden email].
>  
> 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):
>  
>  
>  
> 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=&decision=&token=  
> ```
>  
> 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 ([hidden email]) 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
> > [hidden email]
> > http://w3.org/People/Antonio
> > +81 335162504
> >
> >
> >
>  
>  


Reply | Threaded
Open this post in threaded view
|

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

Robin Berjon-6
In reply to this post by Marcos Caceres-4
Hi Marcos,

thanks for going through this. I'm sorry that your first attempts with
Echidna were a bit painful, it is still an alpha service and the docs
could indeed use some polish. I was luckier than you: the HTML draft
uncovered a few bugs, but after they were fixed things just sailed through.

On 17/03/2015 19:32 , Marcos Caceres wrote:
> # 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**.

It's probably worth noticing that you only need to do that once. After
you have approval, things are automatic.

> ## 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
> [hidden email].

It might be worth noting that it's nicer to ask your team contact than
to make the systeam carry the weight of producing tokens for all.

> ```BASH touch ECHIDNA ```

Note that this file can have any name you want, it's just a manifest.

> 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 ```

It's not clear to me why you're passing configuration options to the
file there. I would presume that shortName is already defined in the
spec. The spec-generator is smart enough to add the specStatus for you,
too. You can just make it be "index.html respec".

It might be worth building a tool that can just update this. Two things
are worth noting:

   - the primary specification file should be first
   - things like .htaccess will be dropped on the floor

> 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:

Note that Specberus (the new pubrules) will support raw ReSpec at some
point. If you have the cycles, feel free to patch it in ;)

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

I guess someone could go *crazy* and build a form for this :)


> 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!).

The curl call above also returns an ID which you can use to check
things. Just go to
https://labs.w3.org/echidna/api/status?id=<the-id-you-got-back> and
you'll get a JSON dump of the status (that is hopefully relatively
self-explanatory). Again, this is a somewhat rough edge, it wouldn't be
the end of the world to slap a UI on top of this.

--
Robin Berjon - http://berjon.com/ - @robinberjon

Reply | Threaded
Open this post in threaded view
|

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

Robin Berjon-6
In reply to this post by Marcos Caceres-4
On 17/03/2015 19:32 , Marcos Caceres wrote:
>(the Echidna Wiki is locked, it seems?):

I forgot to say: I looked at the settings and it does not seem to be
locked. Can you ping me offline to figure out why you can't just edit it?

--
Robin Berjon - http://berjon.com/ - @robinberjon

Reply | Threaded
Open this post in threaded view
|

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

Robin Berjon-6
In reply to this post by Robin Berjon-6
On 18/03/2015 14:15 , Robin Berjon wrote:
>> ```TEXT # ECHIDNA configuration
>> index.html?specStatus=WD;shortName=appmanifest respec
>> images/manifest-src-directive.svg ```
>
> It's not clear to me why you're passing configuration options to the
> file there. I would presume that shortName is already defined in the
> spec. The spec-generator is smart enough to add the specStatus for you,
> too. You can just make it be "index.html respec".

My bad, this isn't there for some reason. I'm looking into it.

--
Robin Berjon - http://berjon.com/ - @robinberjon

Reply | Threaded
Open this post in threaded view
|

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

Denis Ah-Kang
In reply to this post by Robin Berjon-6
On 03/18/2015 09:16 PM, Robin Berjon wrote:
> On 17/03/2015 19:32 , Marcos Caceres wrote:
>> (the Echidna Wiki is locked, it seems?):
>
> I forgot to say: I looked at the settings and it does not seem to be
> locked. Can you ping me offline to figure out why you can't just edit it?
>

It was fixed by Jeremie yesterday :)
See https://github.com/w3c/echidna/issues/128

Denis

Reply | Threaded
Open this post in threaded view
|

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

Marcos Caceres-4
In reply to this post by Robin Berjon-6



On March 18, 2015 at 9:15:43 AM, Robin Berjon ([hidden email]) wrote:
> > The curl call above also returns an ID which you can use to check  
> things. Just go to
> https://labs.w3.org/echidna/api/status?id=(https://labs.w3.org/echidna/api/status?id=%3Cthe-id-you-got-back%3E)  
> and
> you'll get a JSON dump of the status (that is hopefully relatively  
> self-explanatory). Again, this is a somewhat rough edge, it  
> wouldn't be
> the end of the world to slap a UI on top of this.

Agree, but what would be even more awesome and totally badass would be to enable CORS on it. Then we can build our own custom UIs. 

Enabling CORS on a lot of this would enable a lot of great stuff - like one click publication directly from the spec (Editor could just paste in the Token, which is saved securely locally). Then any errors could be reported in the spec itself (as you are working with it locally)... so nice.