[openstack-dev] [openstack-php-sdk] Contributing guidelines

Doug Hellmann doug.hellmann at dreamhost.com
Thu Apr 24 21:14:12 UTC 2014


On Thu, Apr 24, 2014 at 11:18 AM, Matthew Farina <matt at 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.hellmann at dreamhost.com> wrote:
>> On Wed, Apr 23, 2014 at 2:48 PM, Shaunak Kashyap
>> <shaunak.kashyap at 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
>>> OpenStack-dev at lists.openstack.org
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>> _______________________________________________
>> OpenStack-dev mailing list
>> OpenStack-dev at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



More information about the OpenStack-dev mailing list