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
parent
b3dd6a5df1
commit
6827affe62
123
CONTRIBUTING.rst
123
CONTRIBUTING.rst
|
|
@ -1,19 +1,92 @@
|
|||
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
|
||||
Contributing to OpenStack Swift
|
||||
===============================
|
||||
|
||||
Once those steps have been completed, changes to OpenStack should be
|
||||
submitted for review via the Gerrit tool, following the workflow
|
||||
documented at
|
||||
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
|
||||
---------------
|
||||
|
||||
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.
|
||||
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.
|
||||
Bugs should be filed `on Launchpad <https://bugs.launchpad.net/swift>`__,
|
||||
not in GitHub's issue tracker.
|
||||
|
||||
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
|
||||
tree.
|
||||
|
||||
Specs
|
||||
Ideas
|
||||
=====
|
||||
|
||||
.. |swift-specs| replace:: ``swift-specs``
|
||||
.. _swift-specs: https://github.com/openstack/swift-specs
|
||||
https://wiki.openstack.org/wiki/Swift/ideas
|
||||
|
||||
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 <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.
|
||||
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.
|
||||
|
|
|
|||
59
README.rst
59
README.rst
|
|
@ -27,17 +27,50 @@ http://docs.openstack.org/developer/swift/.
|
|||
For Developers
|
||||
--------------
|
||||
|
||||
The best place to get started is the `"SAIO - Swift All In
|
||||
One" <http://docs.openstack.org/developer/swift/development_saio.html>`__.
|
||||
Getting Started
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
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
|
||||
Swift in a VM. The SAIO environment is ideal for running small-scale
|
||||
tests against swift and trying out new features and bug fixes.
|
||||
|
||||
You can run unit tests with ``.unittests`` and functional tests with
|
||||
``.functests``.
|
||||
Tests
|
||||
~~~~~
|
||||
|
||||
If you would like to start contributing, check out these
|
||||
`notes <CONTRIBUTING.md>`__ to help you get started.
|
||||
There are three types of tests included in Swift's source tree.
|
||||
|
||||
#. 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
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -45,19 +78,22 @@ Code Organization
|
|||
- bin/: Executable scripts that are the processes run by the deployer
|
||||
- doc/: Documentation
|
||||
- etc/: Sample config files
|
||||
- examples/: Config snippets used in the docs
|
||||
- swift/: Core code
|
||||
|
||||
- account/: account server
|
||||
- cli/: code that backs some of the CLI tools in bin/
|
||||
- common/: code shared by different modules
|
||||
|
||||
- middleware/: "standard", officially-supported middleware
|
||||
- ring/: code implementing Swift's ring
|
||||
|
||||
- container/: container server
|
||||
- locale/: internationalization (translation) data
|
||||
- obj/: object server
|
||||
- proxy/: proxy server
|
||||
|
||||
- test/: Unit and functional tests
|
||||
- test/: Unit, functional, and probe tests
|
||||
|
||||
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/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
|
||||
``.functests``. These functional tests require ``/etc/swift/test.conf``
|
||||
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
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue