217 lines
7.0 KiB
ReStructuredText
217 lines
7.0 KiB
ReStructuredText
============================
|
|
Contribution getting started
|
|
============================
|
|
|
|
Contributions are highly welcomed and appreciated. Every little help counts,
|
|
so do not hesitate!
|
|
|
|
.. contents:: Contribution links
|
|
:depth: 2
|
|
|
|
|
|
.. _submitplugin:
|
|
|
|
Submit a plugin, co-develop pytest
|
|
----------------------------------
|
|
|
|
Pytest development of the core, some plugins and support code happens
|
|
in repositories living under:
|
|
|
|
- `the pytest-dev bitbucket team <https://bitbucket.org/pytest-dev>`_
|
|
|
|
- `the pytest-dev github organisation <https://github.com/pytest-dev>`_
|
|
|
|
All pytest-dev team members have write access to all contained
|
|
repositories. pytest core and plugins are generally developed
|
|
using `pull requests`_ to respective repositories.
|
|
|
|
You can submit your plugin by subscribing to the `pytest-dev mail list
|
|
<https://mail.python.org/mailman/listinfo/pytest-dev>`_ and writing a
|
|
mail pointing to your existing pytest plugin repository which must have
|
|
the following:
|
|
|
|
- PyPI presence with a ``setup.py`` that contains a license, ``pytest-``
|
|
prefixed, version number, authors, short and long description.
|
|
|
|
- a ``tox.ini`` for running tests using `tox <http://tox.testrun.org>`_.
|
|
|
|
- a ``README.txt`` describing how to use the plugin and on which
|
|
platforms it runs.
|
|
|
|
- a ``LICENSE.txt`` file or equivalent containing the licensing
|
|
information, with matching info in ``setup.py``.
|
|
|
|
- an issue tracker unless you rather want to use the core ``pytest``
|
|
issue tracker.
|
|
|
|
If no contributor strongly objects and two agree, the repo will be
|
|
transferred to the ``pytest-dev`` organisation and you'll become a
|
|
member of the ``pytest-dev`` team, with commit rights to all projects.
|
|
We recommend that each plugin has at least three people who have the
|
|
right to release to pypi.
|
|
|
|
|
|
.. _reportbugs:
|
|
|
|
Report bugs
|
|
-----------
|
|
|
|
Report bugs for pytest at https://bitbucket.org/pytest-dev/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 pytest version.
|
|
* Detailed steps to reproduce the bug.
|
|
|
|
.. _submitfeedback:
|
|
|
|
Submit feedback for developers
|
|
------------------------------
|
|
|
|
Do you like pytest? 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 <https://bitbucket.org/pytest-dev/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, we are very happy for
|
|
:ref:`pull requests <pull-requests>`.
|
|
|
|
.. _fixbugs:
|
|
|
|
Fix bugs
|
|
--------
|
|
|
|
Look through the BitBucket issues for bugs. Here is sample filter you can use:
|
|
https://bitbucket.org/pytest-dev/pytest/issues?status=new&status=open&kind=bug
|
|
|
|
:ref:`Talk <contact>` to developers to find out how you can fix specific bugs.
|
|
|
|
.. _writeplugins:
|
|
|
|
Implement features
|
|
------------------
|
|
|
|
Look through the BitBucket issues for enhancements. Here is sample filter you
|
|
can use:
|
|
https://bitbucket.org/pytest-dev/pytest/issues?status=new&status=open&kind=enhancement
|
|
|
|
:ref:`Talk <contact>` to developers to find out how you can implement specific
|
|
features.
|
|
|
|
Write documentation
|
|
-------------------
|
|
|
|
pytest 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.
|
|
|
|
.. _`pull requests`:
|
|
.. _pull-requests:
|
|
|
|
Preparing Pull Requests on Bitbucket
|
|
------------------------------------
|
|
|
|
.. note::
|
|
What is a "pull request"? It informs project's core developers about the
|
|
changes you want to review and merge. Pull requests are stored on
|
|
`BitBucket servers <https://bitbucket.org/pytest-dev/pytest/pull-requests>`__.
|
|
Once you send pull request, we can discuss it's potential modifications and
|
|
even add more commits to it later on.
|
|
|
|
The primary development platform for pytest is BitBucket. You can find all
|
|
the issues there and submit your pull requests.
|
|
|
|
#. Fork the
|
|
`pytest BitBucket repository <https://bitbucket.org/pytest-dev/pytest>`__. It's
|
|
fine to use ``pytest`` as your fork repository name because it will live
|
|
under your user.
|
|
|
|
#. Create a development environment
|
|
(will implicitly use http://www.virtualenv.org/en/latest/)::
|
|
|
|
$ make develop
|
|
$ source .env/bin/activate
|
|
|
|
#. Clone your fork locally using `Mercurial <http://mercurial.selenic.com/>`_
|
|
(``hg``) and create a branch::
|
|
|
|
$ hg clone ssh://hg@bitbucket.org/YOUR_BITBUCKET_USERNAME/pytest
|
|
$ cd pytest
|
|
$ hg branch your-branch-name
|
|
|
|
If you need some help with Mercurial, follow this quick start
|
|
guide: http://mercurial.selenic.com/wiki/QuickStart
|
|
|
|
#. Create a development environment
|
|
(will implicitly use http://www.virtualenv.org/en/latest/)::
|
|
|
|
$ make develop
|
|
$ source .env/bin/activate
|
|
|
|
#. You can now edit your local working copy.
|
|
|
|
You need to have Python 2.7 and 3.4 available in your system. Now
|
|
running tests is as simple as issuing this command::
|
|
|
|
$ python runtox.py -e py27,py34,flakes
|
|
|
|
This command will run tests via the "tox" tool against Python 2.7 and 3.4
|
|
and also perform "flakes" coding-style checks. ``runtox.py`` is
|
|
a thin wrapper around ``tox`` which installs from a development package
|
|
index where newer (not yet released to pypi) versions of dependencies
|
|
(especially ``py``) might be present.
|
|
|
|
To run tests on py27 and pass options (e.g. enter pdb on failure)
|
|
to pytest you can do::
|
|
|
|
$ python runtox.py -e py27 -- --pdb
|
|
|
|
or to only run tests in a particular test module on py34::
|
|
|
|
$ python runtox.py -e py34 -- testing/test_config.py
|
|
|
|
#. Commit and push once your tests pass and you are happy with your change(s)::
|
|
|
|
$ hg commit -m"<commit message>"
|
|
$ hg push -b .
|
|
|
|
#. Finally, submit a pull request through the BitBucket website:
|
|
|
|
.. image:: img/pullrequest.png
|
|
:width: 700px
|
|
:align: center
|
|
|
|
::
|
|
|
|
source: YOUR_BITBUCKET_USERNAME/pytest
|
|
branch: your-branch-name
|
|
|
|
target: pytest-dev/pytest
|
|
branch: default
|
|
|
|
.. _contribution-using-git:
|
|
|
|
Using git with bitbucket/hg
|
|
-------------------------------
|
|
|
|
There used to be the pytest GitHub mirror. It was removed in favor of the
|
|
Mercurial one, to remove confusion of people not knowing where it's better to
|
|
put their issues and pull requests. Also it wasn't easily possible to automate
|
|
the mirroring process.
|
|
|
|
In general we recommend to work with the same version control system of the
|
|
original repository. If you insist on using git with bitbucket/hg you
|
|
may try `gitifyhg <https://github.com/buchuki/gitifyhg>`_ but are on your
|
|
own and need to submit pull requests through the respective platform,
|
|
nevertheless.
|