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

1 files changed, 52 insertions, 7 deletions

diff --git a/README.rst b/README.rst
index aba20cb90..984d160e2 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" <http://docs.openstack.org/developer/swift/development_saio.html>`__.
+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 <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
-``.functests``.
+Tests
+~~~~~
 
-If you would like to start contributing, check out these
-`notes <CONTRIBUTING.md>`__ 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" <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.