5a7383313b
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
4.7 KiB
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.
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 <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 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
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