Rework the contributor docs

This started as a new "new_contributor" doc. But we've already got
at least 3 different docs like that.

Change-Id: Ia2303ab55eeea01cc71acbccaeab55dad0ef5ff9
This commit is contained in:
John Dickinson 2016-04-05 11:35:22 -07:00
parent b3dd6a5df1
commit 6827affe62
2 changed files with 148 additions and 34 deletions

View File

@ -1,19 +1,92 @@
If you would like to contribute to the development of OpenStack, you Contributing to OpenStack Swift
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 Who is a Contributor?
submitted for review via the Gerrit tool, following the workflow ---------------------
documented at
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
---------------
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. http://docs.openstack.org/infra/manual/developers.html#development-workflow.
Gerrit is the review system used in the OpenStack projects. We're sorry, Gerrit is the review system used in the OpenStack projects. We're sorry, but
but we won't be able to respond to pull requests submitted through we won't be able to respond to pull requests submitted through GitHub.
GitHub.
Bugs should be filed `on Bugs should be filed `on Launchpad <https://bugs.launchpad.net/swift>`__,
Launchpad <https://bugs.launchpad.net/swift>`__, not in GitHub's issue not in GitHub's issue tracker.
tracker.
Swift Design Principles Swift Design Principles
======================= =======================
@ -93,21 +166,17 @@ 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 has passed all automated tests, it will be merged into the Swift source
tree. tree.
Specs Ideas
===== =====
.. |swift-specs| replace:: ``swift-specs`` https://wiki.openstack.org/wiki/Swift/ideas
.. _swift-specs: https://github.com/openstack/swift-specs
The |swift-specs|_ repo If you're working on something, it's a very good idea to write down
can be used for collaborative design work before a feature is what you're thinking about. This lets others get up to speed, helps
implemented. you collaborate, and serves as a great record for future reference.
Write down your thoughts somewhere and put a link to it here. It
OpenStack's gerrit system is used to collaborate on the design spec. doesn't matter what form your thoughts are in; use whatever is best
Once approved OpenStack provides a doc site to easily read these for you. Your document should include why your idea is needed and your
`specs <http://specs.openstack.org/openstack/swift-specs/>`__ thoughts on particular design choices and tradeoffs. Please include
some contact information (ideally, your IRC nick) so that people can
A spec is needed for more impactful features. Coordinating a feature collaborate with you.
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.

View File

@ -27,17 +27,50 @@ http://docs.openstack.org/developer/swift/.
For Developers For Developers
-------------- --------------
The best place to get started is the `"SAIO - Swift All In Getting Started
One" <http://docs.openstack.org/developer/swift/development_saio.html>`__. ~~~~~~~~~~~~~~~
Swift is part of OpenStack and follows the code contribution, review, and testing processes common to all OpenStack projects.
If you would like to start contributing, check out these
`notes <CONTRIBUTING.md>`__ to help you get started.
The best place to get started is the
`"SAIO - Swift All In One" <http://docs.openstack.org/developer/swift/development_saio.html>`__.
This document will walk you through setting up a development cluster of This document will walk you through setting up a development cluster of
Swift in a VM. The SAIO environment is ideal for running small-scale Swift in a VM. The SAIO environment is ideal for running small-scale
tests against swift and trying out new features and bug fixes. tests against swift and trying out new features and bug fixes.
You can run unit tests with ``.unittests`` and functional tests with Tests
``.functests``. ~~~~~
If you would like to start contributing, check out these There are three types of tests included in Swift's source tree.
`notes <CONTRIBUTING.md>`__ to help you get started.
#. Unit tests
#. Functional tests
#. Probe tests
Unit tests check that small sections of the code behave properly. For example,
a unit test may test a single function to ensure that various input gives the
expected output. This validates that the code is correct and regressions are
not introduced.
Functional tests check that the client API is working as expected. These can
be run against any endpoint claiming to support the Swift API (although some
tests require multiple accounts with different privilege levels). These are
"black box" tests that ensure that client apps written against Swift will
continue to work.
Probe tests are "white box" tests that validate the internal workings of a
Swift cluster. They are written to work against the
`"SAIO - Swift All In One" <http://docs.openstack.org/developer/swift/development_saio.html>`__
dev environment. For example, a probe test may create an object, delete one
replica, and ensure that the background consistency processes find and correct
the error.
You can run unit tests with ``.unittests``, functional tests with
``.functests``, and probe tests with ``.probetests``. There is an
additional ``.alltests`` script that wraps the other three.
Code Organization Code Organization
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
@ -45,19 +78,22 @@ Code Organization
- bin/: Executable scripts that are the processes run by the deployer - bin/: Executable scripts that are the processes run by the deployer
- doc/: Documentation - doc/: Documentation
- etc/: Sample config files - etc/: Sample config files
- examples/: Config snippets used in the docs
- swift/: Core code - swift/: Core code
- account/: account server - account/: account server
- cli/: code that backs some of the CLI tools in bin/
- common/: code shared by different modules - common/: code shared by different modules
- middleware/: "standard", officially-supported middleware - middleware/: "standard", officially-supported middleware
- ring/: code implementing Swift's ring - ring/: code implementing Swift's ring
- container/: container server - container/: container server
- locale/: internationalization (translation) data
- obj/: object server - obj/: object server
- proxy/: proxy server - proxy/: proxy server
- test/: Unit and functional tests - test/: Unit, functional, and probe tests
Data Flow Data Flow
~~~~~~~~~ ~~~~~~~~~
@ -77,6 +113,10 @@ Deployer docs are also available at
http://docs.openstack.org/developer/swift/. A good starting point is at http://docs.openstack.org/developer/swift/. A good starting point is at
http://docs.openstack.org/developer/swift/deployment\_guide.html http://docs.openstack.org/developer/swift/deployment\_guide.html
There is an `ops runbook <http://docs.openstack.org/developer/swift/ops_runbook/>`__
that gives information about how to diagnose and troubleshoot common issues
when running a Swift cluster.
You can run functional tests against a swift cluster with You can run functional tests against a swift cluster with
``.functests``. These functional tests require ``/etc/swift/test.conf`` ``.functests``. These functional tests require ``/etc/swift/test.conf``
to run. A sample config file can be found in this source tree in to run. A sample config file can be found in this source tree in
@ -91,6 +131,11 @@ at http://github.com/openstack/python-swiftclient.
Complete API documentation at Complete API documentation at
http://docs.openstack.org/api/openstack-object-storage/1.0/content/ http://docs.openstack.org/api/openstack-object-storage/1.0/content/
There is a large ecosystem of applications and libraries that support and
work with OpenStack Swift. Several are listed on the
`associated projects <http://docs.openstack.org/developer/swift/associated_projects.html>`__
page.
-------------- --------------
For more information come hang out in #openstack-swift on freenode. For more information come hang out in #openstack-swift on freenode.