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

@@ -1,19 +1,92 @@
-If you would like to contribute to the development of OpenStack, you
+Contributing to OpenStack Swift
-must follow the steps in this page:
+===============================
-http://docs.openstack.org/infra/manual/developers.html
 
-Once those steps have been completed, changes to OpenStack should be
+Who is a Contributor?
-submitted for review via the Gerrit tool, following the workflow
+---------------------
-documented at
+
+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 <https://bugs.launchpad.net/swift/+filebug>`__ 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,
+Gerrit is the review system used in the OpenStack projects. We're sorry, but
-but we won't be able to respond to pull requests submitted through
+we won't be able to respond to pull requests submitted through GitHub.
-GitHub.
 
-Bugs should be filed `on
+Bugs should be filed `on Launchpad <https://bugs.launchpad.net/swift>`__,
-Launchpad <https://bugs.launchpad.net/swift>`__, not in GitHub's issue
+not in GitHub's issue tracker.
-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``
+https://wiki.openstack.org/wiki/Swift/ideas
-.. _swift-specs: https://github.com/openstack/swift-specs
 
-The |swift-specs|_ repo
+If you're working on something, it's a very good idea to write down
-can be used for collaborative design work before a feature is
+what you're thinking about. This lets others get up to speed, helps
-implemented.
+you collaborate, and serves as a great record for future reference.
-
+Write down your thoughts somewhere and put a link to it here. It
-OpenStack's gerrit system is used to collaborate on the design spec.
+doesn't matter what form your thoughts are in; use whatever is best
-Once approved OpenStack provides a doc site to easily read these
+for you. Your document should include why your idea is needed and your
-`specs <http://specs.openstack.org/openstack/swift-specs/>`__
+thoughts on particular design choices and tradeoffs. Please include
-
+some contact information (ideally, your IRC nick) so that people can
-A spec is needed for more impactful features. Coordinating a feature
+collaborate with you.
-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.

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
+Getting Started
-One" <http://docs.openstack.org/developer/swift/development_saio.html>`__.
+~~~~~~~~~~~~~~~
+
+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 <CONTRIBUTING.md>`__ to help you get started.
+
+The best place to get started is the
+`"SAIO - Swift All In One" <http://docs.openstack.org/developer/swift/development_saio.html>`__.
 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
+Tests
-``.functests``.
+~~~~~
 
-If you would like to start contributing, check out these
+There are three types of tests included in Swift's source tree.
-`notes <CONTRIBUTING.md>`__ to help you get started.
+
+ #. 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" <http://docs.openstack.org/developer/swift/development_saio.html>`__
+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 <http://docs.openstack.org/developer/swift/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 <http://docs.openstack.org/developer/swift/associated_projects.html>`__
+page.
+
 --------------
 
 For more information come hang out in #openstack-swift on freenode.