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
This commit is contained in:
Carlos Cavanna
John Dickinson
parent
f2e7481f43
commit
5a7383313b
152
doc/source/first_contribution_swift.rst
Normal file
152
doc/source/first_contribution_swift.rst
Normal file
@ -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``
|
||||
|
||||
@ -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
|
||||
installed
|
||||
* :doc:`Swift All in One <development_saio>` - Set up a VM with Swift installed
|
||||
* :doc:`Development Guidelines <development_guidelines>`
|
||||
* :doc:`First Contribution to Swift <first_contribution_swift>`
|
||||
* :doc:`Associated Projects <associated_projects>`
|
||||
|
||||
--------------------------
|
||||
|
||||
@ -68,6 +68,7 @@ Developer Documentation
|
||||
|
||||
development_guidelines
|
||||
development_saio
|
||||
first_contribution_swift
|
||||
policies_saio
|
||||
development_auth
|
||||
development_middleware
|
||||
|
||||
Loading…
Reference in New Issue
Block a user