swift/CONTRIBUTING.rst

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 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

http://docs.openstack.org/developer/swift/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, not in GitHub's issue tracker.

Swift Design Principles

• The Zen of Python
• 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 or the mailing list - we want to help.

Recommended workflow

• Set up a Swift All-In-One VM(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:

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:

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 two 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.