From 6827affe62771949a041d958db17ba6cd29232ab Mon Sep 17 00:00:00 2001 From: John Dickinson Date: Tue, 5 Apr 2016 11:35:22 -0700 Subject: Rework the contributor docs This started as a new "new_contributor" doc. But we've already got at least 3 different docs like that. Change-Id: Ia2303ab55eeea01cc71acbccaeab55dad0ef5ff9 --- CONTRIBUTING.rst | 125 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 97 insertions(+), 28 deletions(-) (limited to 'CONTRIBUTING.rst') diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 0bec89382..e4958f877 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,19 +1,92 @@ -If you would like to contribute to the development of OpenStack, you -must follow the steps in this page: -http://docs.openstack.org/infra/manual/developers.html +Contributing to OpenStack Swift +=============================== -Once those steps have been completed, changes to OpenStack should be -submitted for review via the Gerrit tool, following the workflow -documented at +Who is a Contributor? +--------------------- + +Put simply, if you improve Swift, you're a contributor. The easiest way to +improve the project is to tell us where there's a bug. In other words, filing +a bug is a valuable and helpful way to contribute to the project. + +Once a bug has been filed, someone will work on writing a patch to fix the +bug. Perhaps you'd like to fix a bug. Writing code to fix a bug or add new +functionality is tremendously important. + +Once code has been written, it is submitted upstream for review. All code, +even that written by the most senior members of the community, must pass code +review and all tests before it can be included in the project. Reviewing +proposed patches is a very helpful way to be a contributor. + +Swift is nothing without the community behind it. We'd love to welcome you to +our community. Come find us in #openstack-swift on freenode IRC or on the +OpenStack dev mailing list. + +Filing a Bug +~~~~~~~~~~~~ + +Filing a bug is the easiest way to contribute. We use Launchpad as a bug +tracker; you can find currently-tracked bugs at +https://bugs.launchpad.net/swift. +Use the `Report a bug `__ link to +file a new bug. + +If you find something in Swift that doesn't match the documentation or doesn't +meet your expectations with how it should work, please let us know. Of course, +if you ever get an error (like a Traceback message in the logs), we definitely +want to know about that. We'll do our best to diagnose any problem and patch +it as soon as possible. + +A bug report, at minimum, should describe what you were doing that caused the +bug. "Swift broke, pls fix" is not helpful. Instead, something like "When I +restarted syslog, Swift started logging traceback messages" is very helpful. +The goal is that we can reproduce the bug and isolate the issue in order to +apply a fix. If you don't have full details, that's ok. Anything you can +provide is helpful. + +You may have noticed that there are many tracked bugs, but not all of them +have been confirmed. If you take a look at an old bug report and you can +reproduce the issue described, please leave a comment on the bug about that. +It lets us all know that the bug is very likely to be valid. + +Reviewing Someone Else's Code +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All code reviews in OpenStack projects are done on +https://review.openstack.org/. Reviewing patches is one of the most effective +ways you can contribute to the community. + +We've written REVIEW_GUIDELINES.rst (found in this source tree) to help you +give good reviews. + +https://wiki.openstack.org/wiki/Swift/PriorityReviews is a starting point to +find what reviews are priority in the community. + +What do I work on? +------------------ + +If you're looking for a way to write and contribute code, but you're not sure +what to work on, check out the "wishlist" bugs in the bug tracker. These are +normally smaller items that someone took the time to write down but didn't +have time to implement. + +And please join #openstack-swift on freenode IRC to tell us what you're +working on. + +Getting Started +--------------- + +http://docs.openstack.org/developer/swift/first_contribution_swift.html + +Once those steps have been completed, changes to OpenStack +should be submitted for review via the Gerrit tool, following +the workflow documented at http://docs.openstack.org/infra/manual/developers.html#development-workflow. -Gerrit is the review system used in the OpenStack projects. We're sorry, -but we won't be able to respond to pull requests submitted through -GitHub. +Gerrit is the review system used in the OpenStack projects. We're sorry, but +we won't be able to respond to pull requests submitted through GitHub. -Bugs should be filed `on -Launchpad `__, not in GitHub's issue -tracker. +Bugs should be filed `on Launchpad `__, +not in GitHub's issue tracker. Swift Design Principles ======================= @@ -93,21 +166,17 @@ Once your patch has been reviewed and approved by two core reviewers and has passed all automated tests, it will be merged into the Swift source tree. -Specs +Ideas ===== -.. |swift-specs| replace:: ``swift-specs`` -.. _swift-specs: https://github.com/openstack/swift-specs - -The |swift-specs|_ repo -can be used for collaborative design work before a feature is -implemented. - -OpenStack's gerrit system is used to collaborate on the design spec. -Once approved OpenStack provides a doc site to easily read these -`specs `__ - -A spec is needed for more impactful features. Coordinating a feature -between many devs (especially across companies) is a great example of -when a spec is needed. If you are unsure if a spec document is needed, -please feel free to ask in #openstack-swift on freenode IRC. +https://wiki.openstack.org/wiki/Swift/ideas + +If you're working on something, it's a very good idea to write down +what you're thinking about. This lets others get up to speed, helps +you collaborate, and serves as a great record for future reference. +Write down your thoughts somewhere and put a link to it here. It +doesn't matter what form your thoughts are in; use whatever is best +for you. Your document should include why your idea is needed and your +thoughts on particular design choices and tradeoffs. Please include +some contact information (ideally, your IRC nick) so that people can +collaborate with you. -- cgit v1.2.1