From 5a7383313b1c555df5fd47050f7ee3810b5e31fc Mon Sep 17 00:00:00 2001 From: Carlos Cavanna Date: Tue, 28 Jul 2015 19:15:25 -0400 Subject: [PATCH] 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 | 152 ++++++++++++++++++++++++ doc/source/getting_started.rst | 21 +--- doc/source/index.rst | 1 + 3 files changed, 155 insertions(+), 19 deletions(-) create mode 100644 doc/source/first_contribution_swift.rst diff --git a/doc/source/first_contribution_swift.rst b/doc/source/first_contribution_swift.rst new file mode 100644 index 0000000000..bbd3c65ff8 --- /dev/null +++ b/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 `_. + +Prebuilt packages for Ubuntu and RHEL variants are available. + +* `Swift Ubuntu Packages `_ +* `Swift RDO Packages `_ + +-------------------- +Source Control Setup +-------------------- + +Swift uses `git` for source control. The OpenStack +`Developer's Guide `_ +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 `_ 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 `_ +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 `` + +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 `_ +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: + +* ``_ + +--------------- +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 + from pkg_resources import require + File "/usr/lib/python2.7/dist-packages/pkg_resources.py", line 2749, in + 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`` + diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst index 8e0bbfc7e7..ba8790821b 100644 --- a/doc/source/getting_started.rst +++ b/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 `_. - -Prebuilt packages for Ubuntu and RHEL variants are available. - -* `Swift Ubuntu Packages `_ -* `Swift RDO Packages `_ - ----------- 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 ` - Set up a VM with Swift - installed +* :doc:`Swift All in One ` - Set up a VM with Swift installed * :doc:`Development Guidelines ` +* :doc:`First Contribution to Swift ` * :doc:`Associated Projects ` -------------------------- diff --git a/doc/source/index.rst b/doc/source/index.rst index 45ee1fd0ef..30bfe31808 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -68,6 +68,7 @@ Developer Documentation development_guidelines development_saio + first_contribution_swift policies_saio development_auth development_middleware