Re: [openstack-dev] [openstack-php-sdk] Contributing guidelines
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 QA 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
Re: [openstack-dev] [openstack-php-sdk] Contributing guidelines
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 QA 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@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [openstack-php-sdk] Contributing guidelines
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 QA 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@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
