Swift documentation for first-time contributors.

In this change, there are proposed improvement to Swift documentation aimed at
first-time contributors. They include a simplification of the Getting
Started page and a new page with some basic instructions/commands that the
first-time contributor should know. In addition, it shows some common errors
that the first-time contributor may find when executing git rebase and
information on how to track your changes.

Change-Id: I704202955093736b2f3b4102a649690a0392c6b0

doc/source/first_contribution_swift.rst

@@ -0,0 +1,152 @@
+===========================
+First Contribution to Swift
+===========================
+
+-------------
+Getting Swift
+-------------
+
+Swift's source code is hosted on github and managed with git.  The current
+trunk can be checked out like this:
+
+    ``git clone https://github.com/openstack/swift.git``
+
+This will clone the Swift repository under your account.
+
+A source tarball for the latest release of Swift is available on the
+`launchpad project page <https://launchpad.net/swift>`_.
+
+Prebuilt packages for Ubuntu and RHEL variants are available.
+
+* `Swift Ubuntu Packages <https://launchpad.net/ubuntu/+source/swift>`_
+* `Swift RDO Packages <https://www.rdoproject.org/Repositories>`_
+
+--------------------
+Source Control Setup
+--------------------
+
+Swift uses `git` for source control. The OpenStack
+`Developer's Guide <http://docs.openstack.org/infra/manual/developers.html>`_
+describes the steps for setting up Git and all the necessary accounts for
+contributing code to Swift.
+
+----------------
+Changes to Swift
+----------------
+
+Once you have the source code and source control set up, you can make your
+changes to Swift.
+
+-------
+Testing
+-------
+
+The `Development Guidelines <development_guidelines>`_ describes the testing
+requirements before submitting Swift code.
+
+In summary, you can execute tox from the swift home directory (where you
+checked out the source code):
+
+    ``tox``
+
+Tox will present tests results. Notice that in the beginning, it is very common
+to break many coding style guidelines.
+
+--------------------------
+Proposing changes to Swift
+--------------------------
+
+The OpenStack
+`Developer's Guide <http://docs.openstack.org/infra/manual/developers.html>`_
+describes the most common `git` commands that you will need.
+
+Following is a list of the commands that you need to know for your first
+contribution to Swift:
+
+To clone a copy of Swift:
+
+    ``git clone https://github.com/openstack/swift.git``
+
+Under the swift directory, set up the Gerrit repository. The following command
+configures the repository to know about Gerrit and makes the Change-Id commit
+hook get installed. You only need to do this once:
+
+    ``git review -s``
+
+To create your development branch (substitute branch_name for a name of your
+choice:
+
+    ``git checkout -b <branch_name>``
+
+To check the files that have been updated in your branch:
+
+    ``git status``
+
+To check the differences between your branch and the repository:
+
+    ``git diff``
+
+Assuming you have not added new files, you commit all your changes using:
+
+    ``git commit -a``
+
+Read the `Summary of Git commit message structure <https://wiki.openstack.org/wiki/GitCommitMessages?%22Summary%20of%20Git%20commit%20message%20structure%22#Summary_of_Git_commit_message_structure>`_
+for best practices on writing the commit message. When you are ready to send
+your changes for review use:
+
+    ``git review``
+
+If successful, Git response message will contain a URL you can use to track your
+changes.
+
+If you need to make further changes to the same review, you can commit them
+using:
+
+    ``git commit -a --amend``
+
+This will commit the changes under the same set of changes you issued earlier.
+Notice that in order to send your latest version for review, you will still
+need to call:
+
+    ``git review``
+
+---------------------
+Tracking your changes
+---------------------
+
+After you proposed your changes to Swift, you can track the review in:
+
+* `<https://review.openstack.org>`_
+
+---------------
+Troubleshooting
+---------------
+
+You may run into the following error when starting Swift if you rebase
+your commit using:
+
+    ``git rebase``
+
+.. code-block:: python
+
+   Traceback (most recent call last):
+       File "/usr/local/bin/swift-init", line 5, in <module>
+           from pkg_resources import require
+       File "/usr/lib/python2.7/dist-packages/pkg_resources.py", line 2749, in <module>
+           working_set = WorkingSet._build_master()
+       File "/usr/lib/python2.7/dist-packages/pkg_resources.py", line 446, in _build_master
+           return cls._build_from_requirements(__requires__)
+       File "/usr/lib/python2.7/dist-packages/pkg_resources.py", line 459, in _build_from_requirements
+           dists = ws.resolve(reqs, Environment())
+       File "/usr/lib/python2.7/dist-packages/pkg_resources.py", line 628, in resolve
+           raise DistributionNotFound(req)
+   pkg_resources.DistributionNotFound: swift==2.3.1.devXXX
+   (where XXX represents a dev version of Swift).
+
+This happens because `git rebase` will retrieve code for a different version of
+Swift in the development stream, but the start scripts under `/usr/local/bin` have
+not been updated. The solution is to execute the following command under the swift
+directory (which contains `setup.py`):
+
+    ``sudo python setup.py develop``
+

doc/source/getting_started.rst

@@ -18,23 +18,6 @@ Swift is written in Python and has these dependencies:
 
 There is no current support for Python 3.
 
--------------
-Getting Swift
--------------
-
-Swift's source code is hosted on github and managed with git.  The current
-trunk can be checked out like this:
-
-    ``git clone https://github.com/openstack/swift.git``
-
-A source tarball for the latest release of Swift is available on the
-`launchpad project page <https://launchpad.net/swift>`_.
-
-Prebuilt packages for Ubuntu and RHEL variants are available.
-
-* `Swift Ubuntu Packages <https://launchpad.net/ubuntu/+source/swift>`_
-* `Swift RDO Packages <https://openstack.redhat.com/Repositories>`_
-
 -----------
 Development
 -----------
@@ -42,9 +25,9 @@ Development
 To get started with development with Swift, or to just play around, the
 following docs will be useful:
 
-* :doc:`Swift All in One <development_saio>` - Set up a VM with Swift
+* :doc:`Swift All in One <development_saio>` - Set up a VM with Swift installed
-  installed
 * :doc:`Development Guidelines <development_guidelines>`
+* :doc:`First Contribution to Swift <first_contribution_swift>`
 * :doc:`Associated Projects <associated_projects>`
 
 --------------------------

doc/source/index.rst

@@ -68,6 +68,7 @@ Developer Documentation
 
     development_guidelines
     development_saio
+    first_contribution_swift
     policies_saio
     development_auth
     development_middleware