On Thu, 2015-05-14 at 16:28 -0400, Darryl L. Pierce wrote: > I've pushed these APIs up for public review on their own branch  in > the Apache git repo. They're on a branch named ruby-engine-apis. > > Please take a look, tinker and please provide feedback. :D > >  > http://git-wip-us.apache.org/repos/asf?p=qpid-proton.git;a=shortlog;h=refs/heads/ruby-engine-apis
We have a bunch of new bindings on branches (Go, Ruby, C++) When is a binding ready for trunk? I would propose the following as a basic critiera: - Complete and tested for basic use. - API documentation in language-normal form (godoc, rdoc, doxgygen) - Core set of examples. - Automated testing of all examples. - Getting started README that explains how to run the examples. I would suggest the following core examples for all bindings: - send: connect to endpoint, send N messages. - receive: connect to endpoint, receive N messages. - broker: accept connections, in-memory queues created on demand. - request_response: synchronous request-response client. - echo_server: accept connections, echo message to reply-to address on same connection. This gives us a *small* set of examples that still has good coverage of key scenarios (brokered and client-server) and can be used *without* any external broker. This can be the common introduction to all our bindings. The python binding has all these, with different names. Rationale for proposing the above names: - The simplest send/receive examples should be called simply "send"/"receive". Python has "simple_send"/"simple_receive" which seems redundant. - "request_response" is more descriptive than "sync_client" ("sync_client" is a daft name, my bad) - "echo_server" describes what the server does, just "server" is to generic. The broker is also a server, and there may be other example servers. I can live with the python names if there's a consensus for that but now might be a good time to rationalize. I do think the python examples should be re-organized to start with these core examples. Right now the python README requires you to start by installing an unspecified "intermediary" which is going to cause confusion and frustration. The very first README for every binding should show how to run send/receive examples against the example broker, and request_response against the example server. AFTER we have demonstrated that proton is useful *on its own* we can and should provide further examples of using it with other brokers, tornado, ruby/go/whatever specific frameworks and what have you. Some bindings (Go, possibly C++) provide additional API or toolkit to server multiple connections concurrently. They should also provide concurrent versions of the core examples. The go examples have send and receive take a list of addresses as arguments and send/receive on all addresses concurrently. I would suggest that as a model. Interested in feedback! I'll be working on Go and C++ in coming weeks so I'd like to co-ordinate with ruby and python efforts so we can present something coherent to our users. Cheers, Alan.