merge pbanaszkiewicz/contributiondocs

CONTRIBUTING.rst

@@ -0,0 +1,161 @@
+
+============
+Contributing
+============
+
+Contributions are highly welcomed and appreciated.  Every little help counts,
+so do not hesitate!
+
+Types of contributions
+======================
+
+Submit feedback for developers
+------------------------------
+
+Do you like py.test?  Share some love on Twitter or in your blog posts!
+
+We'd also like to hear about your propositions and suggestions.  Feel free to
+submit them as issues `here <https://bitbucket.org/hpk42/pytest/issues>`__ and:
+
+* Set the "kind" to "enhancement" or "proposal" so that we can quickly find
+  about them.
+* Explain in detail how they should work.
+* Keep the scope as narrow as possible.  This will make it easier to implement.
+* If you have required skills and/or knowledge, you can always contribute to
+  these issues!
+
+Report bugs
+-----------
+
+Report bugs at https://bitbucket.org/hpk42/pytest/issues.
+
+If you are reporting a bug, please include:
+
+* Your operating system name and version.
+* Any details about your local setup that might be helpful in troubleshooting,
+  specifically Python interpreter version,
+  installed libraries and py.test version.
+* Detailed steps to reproduce the bug.
+
+Fix bugs
+--------
+
+Look through the BitBucket issues for bugs.  Here is sample filter you can use:
+https://bitbucket.org/hpk42/pytest/issues?status=new&status=open&kind=bug
+
+:ref:`Talk <contact>` to developers to find out how you can fix specific bugs.
+
+Implement features
+------------------
+
+Look through the BitBucket issues for enhancements.  Here is sample filter you
+can use:
+https://bitbucket.org/hpk42/pytest/issues?status=new&status=open&kind=enhancement
+
+:ref:`Talk <contact>` to developers to find out how you can implement specific
+features.
+
+Write documentation
+-------------------
+
+py.test could always use more documentation.  What exactly is needed?
+
+* More complementary documentation.  Have you perhaps found something unclear?
+* Documentation translations.  We currently have English and Japanese versions.
+* Docstrings.  There's never too much of them.
+* Blog posts, articles and such -- they're all very appreciated.
+
+Getting started for contributing
+================================
+
+The primary development platform for py.test is BitBucket.  You can find all
+the issues there and submit pull requests.  There is, however,
+a `GitHub mirror <https://github.com/hpk42/pytest/>`__ available, too,
+although it only allows for submitting pull requests.  For a GitHub
+contribution guide look :ref:`below <contribution-on-github>`.
+
+1. Fork the py.test `repository <https://bitbucket.org/hpk42/pytest>`__ on BitBucket.
+
+2. Create a local virtualenv (http://www.virtualenv.org/en/latest/)::
+
+    $ virtualenv pytest-venv
+    $ cd pytest-venv/
+    $ source bin/activate
+
+.. _checkout:
+
+3. Clone your fork locally::
+
+    $ hg clone ssh://hg@bitbucket.org/your_name_here/pytest
+
+.. _installing-dev-pytest:
+
+4. Install your local copy into a virtualenv::
+
+    $ cd pytest/
+    $ python setup.py develop
+
+   If that last command complains about not finding the required version
+   of "py" then you need to use the development pypi repository::
+
+    $ python setup.py develop -i http://pypi.testrun.org
+
+.. _testing-pytest:
+
+5. When you're done making changes, check that all of them pass all the tests
+   (including PEP8 and different Python interpreter versions).  First install
+   ``tox``::
+
+    $ pip install tox
+
+  You also need to have Python 2.7 and 3.3 available in your system.  Now
+  running tests is as simple as issuing this one command::
+
+    $ tox -e py27,py33
+
+  This command will run tests for both Python 2.7 and 3.3, which is a minimum
+  required to get your patch merged.  To run whole test suit issue::
+
+    $ tox
+
+6. Commit your changes and push to BitBucket::
+
+    $ hg branch <yourbranchname>
+    $ hg add .
+    $ hg commit -m"<commit message>
+    $ hg push -b .
+
+7. Submit a pull request through the BitBucket website.
+
+
+.. _contribution-on-github:
+What about GitHub?
+------------------
+
+.. warning::
+  Remember that GitHub is **not** a default development platform for py.test
+  and it doesn't include e.g. issue list.
+
+1. Fork the py.test `repository <https://github.com/hpk42/pytest/>`__ on GitHub.
+
+2. Create a local virtualenv (http://www.virtualenv.org/en/latest/)::
+
+    $ virtualenv pytest-venv
+    $ cd pytest-venv/
+
+3. Clone your fork locally::
+
+    $ git clone git@github.com:your_name_here/pytest.git
+
+4. :ref:`Install your local copy into a virtualenv <installing-dev-pytest>`
+   and after that :ref:`test your changes <testing-pytest>`.
+
+5. Commit your changes and push to GitHub::
+
+    $ git branch <yourbranchname>
+    $ git checkout <yourbranchname>
+    $ git add .
+    $ git commit -am"<commit message>"
+    $ git push origin <yourbranchname>
+
+6. Submit a pull request through the GitHub website.

doc/en/contents.txt

@@ -16,7 +16,7 @@ Full pytest documentation
    plugins
    example/index
    talks
-   develop
+   contribute
    funcarg_compare.txt
    announce/index
 

doc/en/contribute.txt

@@ -0,0 +1,3 @@
+.. _contributing:
+
+.. include:: ../../CONTRIBUTING.rst