1============================ 2Contribution getting started 3============================ 4 5Contributions are highly welcomed and appreciated. Every little help counts, 6so do not hesitate! 7 8.. contents:: Contribution links 9 :depth: 2 10 11 12.. _submitfeedback: 13 14Feature requests and feedback 15----------------------------- 16 17Do you like pytest? Share some love on Twitter or in your blog posts! 18 19We'd also like to hear about your propositions and suggestions. Feel free to 20`submit them as issues <https://github.com/pytest-dev/pytest/issues>`_ and: 21 22* Explain in detail how they should work. 23* Keep the scope as narrow as possible. This will make it easier to implement. 24 25 26.. _reportbugs: 27 28Report bugs 29----------- 30 31Report bugs for pytest in the `issue tracker <https://github.com/pytest-dev/pytest/issues>`_. 32 33If you are reporting a bug, please include: 34 35* Your operating system name and version. 36* Any details about your local setup that might be helpful in troubleshooting, 37 specifically the Python interpreter version, installed libraries, and pytest 38 version. 39* Detailed steps to reproduce the bug. 40 41If you can write a demonstration test that currently fails but should pass 42(xfail), that is a very useful commit to make as well, even if you cannot 43fix the bug itself. 44 45 46.. _fixbugs: 47 48Fix bugs 49-------- 50 51Look through the GitHub issues for bugs. Here is a filter you can use: 52https://github.com/pytest-dev/pytest/labels/type%3A%20bug 53 54:ref:`Talk <contact>` to developers to find out how you can fix specific bugs. 55 56Don't forget to check the issue trackers of your favourite plugins, too! 57 58.. _writeplugins: 59 60Implement features 61------------------ 62 63Look through the GitHub issues for enhancements. Here is a filter you can use: 64https://github.com/pytest-dev/pytest/labels/enhancement 65 66:ref:`Talk <contact>` to developers to find out how you can implement specific 67features. 68 69Write documentation 70------------------- 71 72Pytest could always use more documentation. What exactly is needed? 73 74* More complementary documentation. Have you perhaps found something unclear? 75* Documentation translations. We currently have only English. 76* Docstrings. There can never be too many of them. 77* Blog posts, articles and such -- they're all very appreciated. 78 79You can also edit documentation files directly in the GitHub web interface, 80without using a local copy. This can be convenient for small fixes. 81 82.. note:: 83 Build the documentation locally with the following command: 84 85 .. code:: bash 86 87 $ tox -e docs 88 89 The built documentation should be available in the ``doc/en/_build/``. 90 91 Where 'en' refers to the documentation language. 92 93.. _submitplugin: 94 95Submitting Plugins to pytest-dev 96-------------------------------- 97 98Pytest development of the core, some plugins and support code happens 99in repositories living under the ``pytest-dev`` organisations: 100 101- `pytest-dev on GitHub <https://github.com/pytest-dev>`_ 102 103- `pytest-dev on Bitbucket <https://bitbucket.org/pytest-dev>`_ 104 105All pytest-dev Contributors team members have write access to all contained 106repositories. Pytest core and plugins are generally developed 107using `pull requests`_ to respective repositories. 108 109The objectives of the ``pytest-dev`` organisation are: 110 111* Having a central location for popular pytest plugins 112* Sharing some of the maintenance responsibility (in case a maintainer no 113 longer wishes to maintain a plugin) 114 115You can submit your plugin by subscribing to the `pytest-dev mail list 116<https://mail.python.org/mailman/listinfo/pytest-dev>`_ and writing a 117mail pointing to your existing pytest plugin repository which must have 118the following: 119 120- PyPI presence with a ``setup.py`` that contains a license, ``pytest-`` 121 prefixed name, version number, authors, short and long description. 122 123- a ``tox.ini`` for running tests using `tox <https://tox.readthedocs.io>`_. 124 125- a ``README.txt`` describing how to use the plugin and on which 126 platforms it runs. 127 128- a ``LICENSE.txt`` file or equivalent containing the licensing 129 information, with matching info in ``setup.py``. 130 131- an issue tracker for bug reports and enhancement requests. 132 133- a `changelog <http://keepachangelog.com/>`_ 134 135If no contributor strongly objects and two agree, the repository can then be 136transferred to the ``pytest-dev`` organisation. 137 138Here's a rundown of how a repository transfer usually proceeds 139(using a repository named ``joedoe/pytest-xyz`` as example): 140 141* ``joedoe`` transfers repository ownership to ``pytest-dev`` administrator ``calvin``. 142* ``calvin`` creates ``pytest-xyz-admin`` and ``pytest-xyz-developers`` teams, inviting ``joedoe`` to both as **maintainer**. 143* ``calvin`` transfers repository to ``pytest-dev`` and configures team access: 144 145 - ``pytest-xyz-admin`` **admin** access; 146 - ``pytest-xyz-developers`` **write** access; 147 148The ``pytest-dev/Contributors`` team has write access to all projects, and 149every project administrator is in it. We recommend that each plugin has at least three 150people who have the right to release to PyPI. 151 152Repository owners can rest assured that no ``pytest-dev`` administrator will ever make 153releases of your repository or take ownership in any way, except in rare cases 154where someone becomes unresponsive after months of contact attempts. 155As stated, the objective is to share maintenance and avoid "plugin-abandon". 156 157 158.. _`pull requests`: 159.. _pull-requests: 160 161Preparing Pull Requests 162----------------------- 163 164Short version 165~~~~~~~~~~~~~ 166 167#. Fork the repository; 168#. Target ``master`` for bugfixes and doc changes; 169#. Target ``features`` for new features or functionality changes. 170#. Follow **PEP-8**. There's a ``tox`` command to help fixing it: ``tox -e fix-lint``. 171#. Tests are run using ``tox``:: 172 173 tox -e linting,py27,py36 174 175 The test environments above are usually enough to cover most cases locally. 176 177#. Write a ``changelog`` entry: ``changelog/2574.bugfix``, use issue id number 178 and one of ``bugfix``, ``removal``, ``feature``, ``vendor``, ``doc`` or 179 ``trivial`` for the issue type. 180#. Unless your change is a trivial or a documentation fix (e.g., a typo or reword of a small section) please 181 add yourself to the ``AUTHORS`` file, in alphabetical order; 182 183 184Long version 185~~~~~~~~~~~~ 186 187What is a "pull request"? It informs the project's core developers about the 188changes you want to review and merge. Pull requests are stored on 189`GitHub servers <https://github.com/pytest-dev/pytest/pulls>`_. 190Once you send a pull request, we can discuss its potential modifications and 191even add more commits to it later on. There's an excellent tutorial on how Pull 192Requests work in the 193`GitHub Help Center <https://help.github.com/articles/using-pull-requests/>`_. 194 195Here is a simple overview, with pytest-specific bits: 196 197#. Fork the 198 `pytest GitHub repository <https://github.com/pytest-dev/pytest>`__. It's 199 fine to use ``pytest`` as your fork repository name because it will live 200 under your user. 201 202#. Clone your fork locally using `git <https://git-scm.com/>`_ and create a branch:: 203 204 $ git clone git@github.com:YOUR_GITHUB_USERNAME/pytest.git 205 $ cd pytest 206 # now, to fix a bug create your own branch off "master": 207 208 $ git checkout -b your-bugfix-branch-name master 209 210 # or to instead add a feature create your own branch off "features": 211 212 $ git checkout -b your-feature-branch-name features 213 214 Given we have "major.minor.micro" version numbers, bugfixes will usually 215 be released in micro releases whereas features will be released in 216 minor releases and incompatible changes in major releases. 217 218 If you need some help with Git, follow this quick start 219 guide: https://git.wiki.kernel.org/index.php/QuickStart 220 221#. Install tox 222 223 Tox is used to run all the tests and will automatically setup virtualenvs 224 to run the tests in. 225 (will implicitly use http://www.virtualenv.org/en/latest/):: 226 227 $ pip install tox 228 229#. Run all the tests 230 231 You need to have Python 2.7 and 3.6 available in your system. Now 232 running tests is as simple as issuing this command:: 233 234 $ tox -e linting,py27,py36 235 236 This command will run tests via the "tox" tool against Python 2.7 and 3.6 237 and also perform "lint" coding-style checks. 238 239#. You can now edit your local working copy. Please follow PEP-8. 240 241 You can now make the changes you want and run the tests again as necessary. 242 243 If you have too much linting errors, try running:: 244 245 $ tox -e fix-lint 246 247 To fix pep8 related errors. 248 249 You can pass different options to ``tox``. For example, to run tests on Python 2.7 and pass options to pytest 250 (e.g. enter pdb on failure) to pytest you can do:: 251 252 $ tox -e py27 -- --pdb 253 254 Or to only run tests in a particular test module on Python 3.6:: 255 256 $ tox -e py36 -- testing/test_config.py 257 258#. Commit and push once your tests pass and you are happy with your change(s):: 259 260 $ git commit -a -m "<commit message>" 261 $ git push -u 262 263#. Create a new changelog entry in ``changelog``. The file should be named ``<issueid>.<type>``, 264 where *issueid* is the number of the issue related to the change and *type* is one of 265 ``bugfix``, ``removal``, ``feature``, ``vendor``, ``doc`` or ``trivial``. 266 267#. Add yourself to ``AUTHORS`` file if not there yet, in alphabetical order. 268 269#. Finally, submit a pull request through the GitHub website using this data:: 270 271 head-fork: YOUR_GITHUB_USERNAME/pytest 272 compare: your-branch-name 273 274 base-fork: pytest-dev/pytest 275 base: master # if it's a bugfix 276 base: features # if it's a feature 277 278 279