Subject: [hybi] WAMP RFC Draft Critique

From: Emile Cormier <[email-masked]>
Date: Mon, 5 Oct 2015 00:33:16 -0300

First, let me say that I am very happy to see WAMP being drafted as an IETF
RFC. We at Butterfly Energy Systems are currently using WAMP as the
backbone for an upcoming building automation system. The integration of
PubSub and RPC within the same protocol works beautifully for a system that
needs to perform both monitoring and control. The language-agnostic nature
of WAMP allows us to use Javascript on the web front-end, while being able
to use C++ on the backend, all without having to write a "middleman" web
server app.

I started reviewing the WAMP RFC draft. I wanted to be able to add comments
to the text, annotate changes for fixing spelling/grammar, and annotate
changes for improving the English prose. My proposed changes are too
numerous to be done via email on a mailing list. I figured the best way to
proceed was to simply annotate changes in my own GitHub fork of the WAMP
RFC. If there is a better workflow for collaboration on the same Markdown
document, please let me know.

So far, I've only had the chance to review up to the Design Philosophy
section. Please see
https://github.com/ecorm/wamp-proto/blob/ecorm-rfc-critique-1/rfc/draft-oberstet-hybi-tavendo-wamp-00.md.
I'll try to complete my review during the next few weeks.

I used strikethrough wherever I made edits. I also used blockquotes as a
way to insert my comments.

If most of my proposed changes are acceptable, then I can submit a pull
request that would be more easily mergeable. We can use the Review Comments
feature of GitHub's pull request to discuss my proposed edits. While
merging, Tobias/Alex can pick and choose which edits they want to keep and
those they prefer to reject. We can post links to the pull requests on this
mailing list to keep everyone informed.

Please let me know if this way of proceeding is sensible, or if there is a
better way.

Cheers,
Emile Cormier

---

From: Tobias Oberstein <[email-masked]>
Date: Mon, 5 Oct 2015 10:14:46 +0200

Hi Emile,

 > I started reviewing the WAMP RFC draft. I wanted to be able to add
> comments to the text, annotate changes for fixing spelling/grammar, and
> annotate changes for improving the English prose. My proposed changes
> are too numerous to be done via email on a mailing list. I figured the
> best way to proceed was to simply annotate changes in my own GitHub fork
> of the WAMP RFC. If there is a better workflow for collaboration on the
> same Markdown document, please let me know.

I think what you touch here is a general, important question: workflow.

Historically, we've been using a GitHub based workflow for collaborating 
on the WAMP spec: GH issues and discussion there plus pull-requests to 
merge in changes.

This works quite well .. eg. I am able to review (and comment) on your 
changes easily:

> request that would be more easily mergeable. We can use the Review
> Comments feature of GitHub's pull request to discuss my proposed edits.
> While merging, Tobias/Alex can pick and choose which edits they want to
> keep and those they prefer to reject. We can post links to the pull
> requests on this mailing list to keep everyone informed.
>
> Please let me know if this way of proceeding is sensible, or if there is
> a better way.
>
> Cheers,
> Emile Cormier

---

From: Tobias Oberstein <[email-masked]>
Date: Mon, 5 Oct 2015 10:19:24 +0200

sorry, accidently hit send .. here is my full reply.

This works quite well .. eg. one can review (and comment) on your
changes easily:

https://github.com/ecorm/wamp-proto/commit/7b6c3a75a031e113cdd81931866fce0ff7d6cabf

Doing the same via a strict mail based workflow seems harder.

@Salvatore
Are there IETF rules on _how_ working on a RFC draft must happen?
Any guidelines from your side on how we should proceed?

Cheers,
/Tobias

---

From: Takeshi Yoshino <[email-masked]>
Date: Mon, 5 Oct 2015 21:50:23 +0900

What I saw on HTTP/2 standardization was:
- pull requests were reviewed and accepted at GitHub.
- the co-editor, Martin, published snapshot at IETF data tracker
periodically.
- questions were raised at the GitHub issue tracker and were taken by the
editor
- but the chair, Mark, guided people to the WG list when non-trivial
discussion happened at GitHub
https://github.com/http2/http2-spec/issues/612#issuecomment-57949294

HyBi may also have to follow the 4th point, I guess. Not sure.

Takeshi

On Mon, Oct 5, 2015 at 5:19 PM, Tobias Oberstein <
[email-masked]> wrote:

> _______________________________________________
> hybi mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/hybi
>

---

From: Emile Cormier <[email-masked]>
Date: Mon, 5 Oct 2015 10:28:33 -0300

In case it matters, I should disclose to the mailing list that I'm the
author of CppWAMP, a C++ WAMP client implementation:
https://github.com/ecorm/cppwamp

On Mon, Oct 5, 2015 at 12:33 AM, Emile Cormier <[email-masked]>
wrote:

> First, let me say that I am very happy to see WAMP being drafted as an
> IETF RFC. We at Butterfly Energy Systems are currently using WAMP as the
> annotate changes for improving the English prose. My proposed changes are
> too numerous to be done via email on a mailing list. I figured the best way
> to proceed was to simply annotate changes in my own GitHub fork of the WAMP

---

From: Tobias Oberstein <[email-masked]>
Date: Mon, 5 Oct 2015 21:24:08 +0200

Am 05.10.2015 um 14:50 schrieb Takeshi Yoshino:
> - questions were raised at the GitHub issue tracker and were taken by
> the editor

Interesting! Thanks for pointing out.

So if we manage to raise enough interest and the Hybi WG and chairs 
would accept working on WAMP as a WG item and support a workflow similar 
to what HTTP/2 did, we could continue with a (mainly) GitHub based 
workflow. Awesome!

> HyBi may also have to follow the 4th point, I guess. Not sure.

Ah, ok. So it'll depend on how and where the chairs want to see extended 
discussions happen.

--

We already moved the repo from GH/Tavendo to a "neutral", dedicated place:

https://github.com/wamp-proto/wamp-proto

Also: the repo is IMO some proof that there is interest. We have 17 
contributors on the repo and something like 500 commmits. Not all of 
those commits are strictly touching the spec .. the repo was 
historically used also for the WAMP Web site (which we now moved out to 
https://github.com/wamp-proto/wamp-web)

FWIW, https://github.com/http2/http2-spec has 42 contributors and 2000 
commits (no surprise here of course).

Thanks Takeshi!

/Tobias

---

From: Simone Bordet <[email-masked]>
Date: Mon, 5 Oct 2015 21:31:17 +0200

Hi,

> HyBi may also have to follow the 4th point, I guess. Not sure.

Actually, Mark changed his mind on this fourth bullet to reduce
traffic on that mailing list, so now discussions are on GitHub:
https://lists.w3.org/Archives/Public/ietf-http-wg/2015OctDec/0027.html

-- 
Simone Bordet
http://bordet.blogspot.com
---
Finally, no matter how good the architecture and design are,
to deliver bug-free software with optimal performance and reliability,
the implementation technique must be flawless.   Victoria Livschitz

---

From: Emile Cormier <[email-masked]>
Date: Mon, 5 Oct 2015 19:33:32 -0300

> https://github.com/ecorm/wamp-proto/commit/7b6c3a75a031e113cdd81931866fce0ff7d6cabf
Instead of using blockquotes for my comments, I can just use the GH comment
system within my own PR/commit. That'll make it easier to merge things.

I going to start over my review in a new branch within my fork.

---

From: Takeshi Yoshino <[email-masked]>
Date: Tue, 6 Oct 2015 12:20:25 +0900

> https://lists.w3.org/Archives/Public/ietf-http-wg/2015OctDec/0027.html
Oh, thanks for correction!