Doug, I have a few concerns with handling the PHP SDK this way. The authors of the novaclient are working on openstack, using python which has common community processes, and there is a bit of documentation covering the commonalities. Contributors to the PHP SDK are likely not going to know how the community works for creating an infrastructure. In PHP there will be some major process differences to fit into the PHP community and be native to PHP.
The target audience for the PHP SDK is application developers, not those who write openstack or operate it. A contributors guide who really hits home with this audience is important. There are definitely things we can link off to. I just want to make sure we hit home with our target audiences. On Thu, Apr 24, 2014 at 5:14 PM, Doug Hellmann <doug.hellm...@dreamhost.com> wrote: > On Thu, Apr 24, 2014 at 11:18 AM, Matthew Farina <m...@mattfarina.com> wrote: >> Doug, I think contributing to the PHP SDK is going to be a little >> different than a lot of other OpenStack contributions. For example, >> these are application developers rather than those who develop or >> standup OpenStack as infrastructure. There is a lot about OpenStack >> they don't need to know. We need to take that into account. >> >> Not to mention that this is a different language from the services. In >> my experience, a lot of PHP developers will never jump into >> contributing in other languages. > > Especially when it comes to processes, we can be consistent with our > established community standards no matter what language we're writing > in. The python-novaclient repository has something similar to what I'm > suggesting, combining usage info with links to source, the bug > tracker, and instructions for using gerrit > (http://git.openstack.org/cgit/openstack/python-novaclient/tree/doc/source/index.rst). > > Doug > >> >> We've also talked about having the documentation be usage >> documentation rather than contributing documentation. This is >> important as SDK users want a single package they download that gives >> them everything they need to get going with OpenStack. Pointing them >> to some other place to get started is a barrier to building against >> OpenStack. >> >> This is why I'm hesitant to suggest we do something similar to what >> you'd see with Swift, Nova, or something else. The context is quite >> different for someone approaching this project. >> >> Shaunak, this sounds like a good idea. Did you want to create a >> blueprint for it and we can work out the spec for what could or should >> be listed? Other SDKs in this space do something similar that helps >> folks get up to speed on the SDK quickly. >> >> One addition to your list would be, how to get started contributing to >> OpenStack. We need to guide folks to the CLA and anything else they >> need to get going. >> >> This would be great for the developer experience of contributing to the SDK. >> >> >> On Thu, Apr 24, 2014 at 10:29 AM, Doug Hellmann >> <doug.hellm...@dreamhost.com> wrote: >>> On Wed, Apr 23, 2014 at 2:48 PM, Shaunak Kashyap >>> <shaunak.kash...@rackspace.com> wrote: >>>> Hey PHP SDK folks (although others are welcome to chime in too), >>>> >>>> I am thinking of adding a CONTRIBUTING.rst to the root of our repo at >>>> http://git.openstack.org/cgit/stackforge/openstack-sdk-php/tree/. My >>>> immediate, selfish need is to have a single place where we capture any >>>> decisions around contribution process so I don’t have to remember them or >>>> rehash them often. Longer term I think this would be useful to all >>>> potential contributors - in making them feel welcome and less overwhelmed >>>> - especially as the project grows. >>>> >>>> If you think this would be a useful addition, please read on. >>>> >>>> Putting on a new contributor’s hat, here are some of the questions (in no >>>> particular order) that come to my mind when I encounter a new project: >>>> >>>> 1. What is the overall development process? >>>> 2. I see a bunch of directories and files in the source tree. What do >>>> these mean? >>>> 3. What do I need to setup in my development environment so I can >>>> contribute? >>>> 4. Are there any coding standards I should adhere to? >>>> 5. I'm ready to submit my first patch. What happens next? >>>> 6. How do I run the unit tests? >>>> 7. How do I run the integration tests? >>>> >>>> Can you think of more questions, ones you might’ve had in the past perhaps? >>>> >>>> I imagine the CONTRIBUTING.rst to be comprised of answers to these >>>> questions (but perhaps not necessarily in Q&A format). I realize that some >>>> of these answers would overlap with information that already exists >>>> elsewhere. We would link to those sources while still giving our >>>> contributors a single starting point within the context of our project. >>>> >>>> Please note that, at this time, I’m just soliciting approval for having a >>>> CONTRIBUTING.rst and coming up with the list of questions that it would >>>> answer. I am not (yet) looking for us to come up with all the answers and >>>> agree on them as a team. >>>> >>>> Thoughts? >>> >>> These are all good questions for helping out new and infrequent >>> contributors. Many of the other projects answer those sorts of >>> questions in the developer documentation (under doc/source in the >>> repository) and have a boilerplate CONTRIBUTING.rst file that points >>> to the OpenStack wiki for workflow information, so you might consider >>> doing something similar. >>> >>> Doug >>> >>>> >>>> Shaunak >>>> >>>> >>>> >>>> _______________________________________________ >>>> OpenStack-dev mailing list >>>> OpenStackfirstname.lastname@example.org >>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >>> >>> _______________________________________________ >>> OpenStack-dev mailing list >>> OpenStackemail@example.com >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >> >> _______________________________________________ >> OpenStack-dev mailing list >> OpenStackfirstname.lastname@example.org >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > _______________________________________________ > OpenStack-dev mailing list > OpenStackemail@example.com > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev _______________________________________________ OpenStack-dev mailing list OpenStackfirstname.lastname@example.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev