183 lines
7.0 KiB
ReStructuredText
183 lines
7.0 KiB
ReStructuredText
Contributing to OpenStack Swift
|
|
===============================
|
|
|
|
Who is a Contributor?
|
|
---------------------
|
|
|
|
Put simply, if you improve Swift, you're a contributor. The easiest way to
|
|
improve the project is to tell us where there's a bug. In other words, filing
|
|
a bug is a valuable and helpful way to contribute to the project.
|
|
|
|
Once a bug has been filed, someone will work on writing a patch to fix the
|
|
bug. Perhaps you'd like to fix a bug. Writing code to fix a bug or add new
|
|
functionality is tremendously important.
|
|
|
|
Once code has been written, it is submitted upstream for review. All code,
|
|
even that written by the most senior members of the community, must pass code
|
|
review and all tests before it can be included in the project. Reviewing
|
|
proposed patches is a very helpful way to be a contributor.
|
|
|
|
Swift is nothing without the community behind it. We'd love to welcome you to
|
|
our community. Come find us in #openstack-swift on freenode IRC or on the
|
|
OpenStack dev mailing list.
|
|
|
|
Filing a Bug
|
|
~~~~~~~~~~~~
|
|
|
|
Filing a bug is the easiest way to contribute. We use Launchpad as a bug
|
|
tracker; you can find currently-tracked bugs at
|
|
https://bugs.launchpad.net/swift.
|
|
Use the `Report a bug <https://bugs.launchpad.net/swift/+filebug>`__ link to
|
|
file a new bug.
|
|
|
|
If you find something in Swift that doesn't match the documentation or doesn't
|
|
meet your expectations with how it should work, please let us know. Of course,
|
|
if you ever get an error (like a Traceback message in the logs), we definitely
|
|
want to know about that. We'll do our best to diagnose any problem and patch
|
|
it as soon as possible.
|
|
|
|
A bug report, at minimum, should describe what you were doing that caused the
|
|
bug. "Swift broke, pls fix" is not helpful. Instead, something like "When I
|
|
restarted syslog, Swift started logging traceback messages" is very helpful.
|
|
The goal is that we can reproduce the bug and isolate the issue in order to
|
|
apply a fix. If you don't have full details, that's ok. Anything you can
|
|
provide is helpful.
|
|
|
|
You may have noticed that there are many tracked bugs, but not all of them
|
|
have been confirmed. If you take a look at an old bug report and you can
|
|
reproduce the issue described, please leave a comment on the bug about that.
|
|
It lets us all know that the bug is very likely to be valid.
|
|
|
|
Reviewing Someone Else's Code
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
All code reviews in OpenStack projects are done on
|
|
https://review.openstack.org/. Reviewing patches is one of the most effective
|
|
ways you can contribute to the community.
|
|
|
|
We've written REVIEW_GUIDELINES.rst (found in this source tree) to help you
|
|
give good reviews.
|
|
|
|
https://wiki.openstack.org/wiki/Swift/PriorityReviews is a starting point to
|
|
find what reviews are priority in the community.
|
|
|
|
What do I work on?
|
|
------------------
|
|
|
|
If you're looking for a way to write and contribute code, but you're not sure
|
|
what to work on, check out the "wishlist" bugs in the bug tracker. These are
|
|
normally smaller items that someone took the time to write down but didn't
|
|
have time to implement.
|
|
|
|
And please join #openstack-swift on freenode IRC to tell us what you're
|
|
working on.
|
|
|
|
Getting Started
|
|
---------------
|
|
|
|
https://docs.openstack.org/swift/latest/first_contribution_swift.html
|
|
|
|
Once those steps have been completed, changes to OpenStack
|
|
should be submitted for review via the Gerrit tool, following
|
|
the workflow documented at
|
|
http://docs.openstack.org/infra/manual/developers.html#development-workflow.
|
|
|
|
Gerrit is the review system used in the OpenStack projects. We're sorry, but
|
|
we won't be able to respond to pull requests submitted through GitHub.
|
|
|
|
Bugs should be filed `on Launchpad <https://bugs.launchpad.net/swift>`__,
|
|
not in GitHub's issue tracker.
|
|
|
|
Swift Design Principles
|
|
=======================
|
|
|
|
- `The Zen of Python <http://legacy.python.org/dev/peps/pep-0020/>`__
|
|
- Simple Scales
|
|
- Minimal dependencies
|
|
- Re-use existing tools and libraries when reasonable
|
|
- Leverage the economies of scale
|
|
- Small, loosely coupled RESTful services
|
|
- No single points of failure
|
|
- Start with the use case
|
|
- ... then design from the cluster operator up
|
|
- If you haven't argued about it, you don't have the right answer yet
|
|
:)
|
|
- If it is your first implementation, you probably aren't done yet :)
|
|
|
|
Please don't feel offended by difference of opinion. Be prepared to
|
|
advocate for your change and iterate on it based on feedback. Reach out
|
|
to other people working on the project on
|
|
`IRC <http://eavesdrop.openstack.org/irclogs/%23openstack-swift/>`__ or
|
|
the `mailing
|
|
list <http://lists.openstack.org/pipermail/openstack-dev/>`__ - we want
|
|
to help.
|
|
|
|
Recommended workflow
|
|
====================
|
|
|
|
- Set up a `Swift All-In-One
|
|
VM <https://docs.openstack.org/swift/latest/development_saio.html>`__\ (SAIO).
|
|
|
|
- Make your changes. Docs and tests for your patch must land before or
|
|
with your patch.
|
|
|
|
- Run unit tests, functional tests, probe tests ``./.unittests``
|
|
``./.functests`` ``./.probetests``
|
|
|
|
- Run ``tox`` (no command-line args needed)
|
|
|
|
- ``git review``
|
|
|
|
Notes on Testing
|
|
================
|
|
|
|
Running the tests above against Swift in your development environment
|
|
(ie your SAIO) will catch most issues. Any patch you propose is expected
|
|
to be both tested and documented and all tests should pass.
|
|
|
|
If you want to run just a subset of the tests while you are developing,
|
|
you can use nosetests:
|
|
|
|
.. code-block:: console
|
|
|
|
cd test/unit/common/middleware/ && nosetests test_healthcheck.py
|
|
|
|
To check which parts of your code are being exercised by a test, you can
|
|
run tox and then point your browser to swift/cover/index.html:
|
|
|
|
.. code-block:: console
|
|
|
|
tox -e py27 -- test.unit.common.middleware.test_healthcheck:TestHealthCheck.test_healthcheck
|
|
|
|
Swift's unit tests are designed to test small parts of the code in
|
|
isolation. The functional tests validate that the entire system is
|
|
working from an external perspective (they are "black-box" tests). You
|
|
can even run functional tests against public Swift endpoints. The
|
|
probetests are designed to test much of Swift's internal processes. For
|
|
example, a test may write data, intentionally corrupt it, and then
|
|
ensure that the correct processes detect and repair it.
|
|
|
|
When your patch is submitted for code review, it will automatically be
|
|
tested on the OpenStack CI infrastructure. In addition to many of the
|
|
tests above, it will also be tested by several other OpenStack test
|
|
jobs.
|
|
|
|
Once your patch has been reviewed and approved by core reviewers and
|
|
has passed all automated tests, it will be merged into the Swift source
|
|
tree.
|
|
|
|
Ideas
|
|
=====
|
|
|
|
https://wiki.openstack.org/wiki/Swift/ideas
|
|
|
|
If you're working on something, it's a very good idea to write down
|
|
what you're thinking about. This lets others get up to speed, helps
|
|
you collaborate, and serves as a great record for future reference.
|
|
Write down your thoughts somewhere and put a link to it here. It
|
|
doesn't matter what form your thoughts are in; use whatever is best
|
|
for you. Your document should include why your idea is needed and your
|
|
thoughts on particular design choices and tradeoffs. Please include
|
|
some contact information (ideally, your IRC nick) so that people can
|
|
collaborate with you.
|