From 6827affe62771949a041d958db17ba6cd29232ab Mon Sep 17 00:00:00 2001 From: John Dickinson Date: Tue, 5 Apr 2016 11:35:22 -0700 Subject: [PATCH] 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 | 123 ++++++++++++++++++++++++++++++++++++----------- README.rst | 59 ++++++++++++++++++++--- 2 files changed, 148 insertions(+), 34 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 0bec893829..e4958f8772 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 +https://wiki.openstack.org/wiki/Swift/ideas -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. +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. diff --git a/README.rst b/README.rst index aba20cb903..984d160e21 100644 --- a/README.rst +++ b/README.rst @@ -27,17 +27,50 @@ http://docs.openstack.org/developer/swift/. For Developers -------------- -The best place to get started is the `"SAIO - Swift All In -One" `__. +Getting Started +~~~~~~~~~~~~~~~ + +Swift is part of OpenStack and follows the code contribution, review, and testing processes common to all OpenStack projects. + +If you would like to start contributing, check out these +`notes `__ to help you get started. + +The best place to get started is the +`"SAIO - Swift All In One" `__. This document will walk you through setting up a development cluster of Swift in a VM. The SAIO environment is ideal for running small-scale tests against swift and trying out new features and bug fixes. -You can run unit tests with ``.unittests`` and functional tests with -``.functests``. +Tests +~~~~~ -If you would like to start contributing, check out these -`notes `__ to help you get started. +There are three types of tests included in Swift's source tree. + + #. Unit tests + #. Functional tests + #. Probe tests + +Unit tests check that small sections of the code behave properly. For example, +a unit test may test a single function to ensure that various input gives the +expected output. This validates that the code is correct and regressions are +not introduced. + +Functional tests check that the client API is working as expected. These can +be run against any endpoint claiming to support the Swift API (although some +tests require multiple accounts with different privilege levels). These are +"black box" tests that ensure that client apps written against Swift will +continue to work. + +Probe tests are "white box" tests that validate the internal workings of a +Swift cluster. They are written to work against the +`"SAIO - Swift All In One" `__ +dev environment. For example, a probe test may create an object, delete one +replica, and ensure that the background consistency processes find and correct +the error. + +You can run unit tests with ``.unittests``, functional tests with +``.functests``, and probe tests with ``.probetests``. There is an +additional ``.alltests`` script that wraps the other three. Code Organization ~~~~~~~~~~~~~~~~~ @@ -45,19 +78,22 @@ Code Organization - bin/: Executable scripts that are the processes run by the deployer - doc/: Documentation - etc/: Sample config files +- examples/: Config snippets used in the docs - swift/: Core code - account/: account server + - cli/: code that backs some of the CLI tools in bin/ - common/: code shared by different modules - middleware/: "standard", officially-supported middleware - ring/: code implementing Swift's ring - container/: container server + - locale/: internationalization (translation) data - obj/: object server - proxy/: proxy server -- test/: Unit and functional tests +- test/: Unit, functional, and probe tests Data Flow ~~~~~~~~~ @@ -77,6 +113,10 @@ Deployer docs are also available at http://docs.openstack.org/developer/swift/. A good starting point is at http://docs.openstack.org/developer/swift/deployment\_guide.html +There is an `ops runbook `__ +that gives information about how to diagnose and troubleshoot common issues +when running a Swift cluster. + You can run functional tests against a swift cluster with ``.functests``. These functional tests require ``/etc/swift/test.conf`` to run. A sample config file can be found in this source tree in @@ -91,6 +131,11 @@ at http://github.com/openstack/python-swiftclient. Complete API documentation at http://docs.openstack.org/api/openstack-object-storage/1.0/content/ +There is a large ecosystem of applications and libraries that support and +work with OpenStack Swift. Several are listed on the +`associated projects `__ +page. + -------------- For more information come hang out in #openstack-swift on freenode.