diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 1f69a82562..0000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,98 +0,0 @@ -If you would like to contribute to the development of OpenStack, -you must follow the steps in this page: [http://docs.openstack.org/infra/manual/developers.html](http://docs.openstack.org/infra/manual/developers.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](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](http://docs.openstack.org/developer/swift/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:: - - 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. - -Specs -===== - -The [``swift-specs``](https://github.com/openstack/swift-specs) repo -can be used for collaborative design work before a feature is implemented. - -OpenStack's gerrit system is used to collaborate on the design spec. Once -approved OpenStack provides a doc site to easily read these [specs](http://specs.openstack.org/openstack/swift-specs/) - -A spec is needed for more impactful features. Coordinating a feature between -many devs (especially across companies) is a great example of when a spec is -needed. If you are unsure if a spec document is needed, please feel free to -ask in #openstack-swift on freenode IRC. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 0000000000..0bec893829 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,113 @@ +If you would like to contribute to the development of OpenStack, you +must follow the steps in this page: +http://docs.openstack.org/infra/manual/developers.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: + +.. 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 two core reviewers and +has passed all automated tests, it will be merged into the Swift source +tree. + +Specs +===== + +.. |swift-specs| replace:: ``swift-specs`` +.. _swift-specs: https://github.com/openstack/swift-specs + +The |swift-specs|_ repo +can be used for collaborative design work before a feature is +implemented. + +OpenStack's gerrit system is used to collaborate on the design spec. +Once approved OpenStack provides a doc site to easily read these +`specs `__ + +A spec is needed for more impactful features. Coordinating a feature +between many devs (especially across companies) is a great example of +when a spec is needed. If you are unsure if a spec document is needed, +please feel free to ask in #openstack-swift on freenode IRC. diff --git a/MANIFEST.in b/MANIFEST.in index 0a2da4a617..bcbc015d33 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,5 +1,5 @@ include AUTHORS LICENSE .functests .unittests .probetests test/__init__.py -include CHANGELOG CONTRIBUTING.md README.md +include CHANGELOG CONTRIBUTING.rst README.md include babel.cfg include test/sample.conf include tox.ini