From fa7b0086a28a8ba42919dee450bc38bb27f4ed8a Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Thu, 18 Feb 2016 19:13:29 -0200 Subject: [PATCH 1/2] Move sections around (from easier to hardest) and added howto for repo transfers #1282 --- CONTRIBUTING.rst | 139 +++++++++++++++++++++++++++++------------------ 1 file changed, 86 insertions(+), 53 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 2bee8b17e..bd2bad34b 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -9,46 +9,18 @@ so do not hesitate! :depth: 2 -.. _submitplugin: +.. _submitfeedback: -Submit a plugin, co-develop pytest ----------------------------------- +Feature requests and feedback +----------------------------- -Pytest development of the core, some plugins and support code happens -in repositories living under: +Do you like pytest? Share some love on Twitter or in your blog posts! -- `the pytest-dev github organisation `_ +We'd also like to hear about your propositions and suggestions. Feel free to +`submit them as issues `__ and: -- `the pytest-dev bitbucket team `_ - -All pytest-dev Contributors 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 -`_ 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 `_. - -- 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 Contributors`` 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. +* Explain in detail how they should work. +* Keep the scope as narrow as possible. This will make it easier to implement. .. _reportbugs: @@ -56,7 +28,7 @@ people who have the right to release to pypi. Report bugs ----------- -Report bugs for pytest at https://github.com/pytest-dev/pytest/issues +Report bugs for pytest in the `issue tracker `_. If you are reporting a bug, please include: @@ -70,22 +42,6 @@ If you can write a demonstration test that currently fails but should pass (xfai that is a very useful commit to make as well, even if you can't find how to fix the bug yet. -.. _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 `__ 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 `. .. _fixbugs: @@ -125,12 +81,89 @@ You can also edit documentation files directly in the Github web interface without needing to make a fork and local copy. This can be convenient for small fixes. + +.. _submitplugin: + +Submitting Plugins to pytest-dev +-------------------------------- + +Pytest development of the core, some plugins and support code happens +in repositories living under the ``pytest-dev`` organisations: + +- `pytest-dev on GitHub `_ + +- `pytest-dev on Bitbucket `_ + +All pytest-dev Contributors team members have write access to all contained +repositories. pytest core and plugins are generally developed +using `pull requests`_ to respective repositories. + +The objectives of the ``pytest-dev`` organisation are: + +* Having a central location for popular pytest plugins +* Sharing some of the maintenance responsibility (in case a maintainer no longer whishes to maintain a plugin) + +You can submit your plugin by subscribing to the `pytest-dev mail list +`_ 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 `_. + +- 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 repository can then be +transferred to the ``pytest-dev`` organisation. + +Here's a rundown of how a repository transfer usually proceeds +(using a repository named ``joedoe/pytest-xyz`` as an example): + +* One of the ``pytest-dev`` administrators creates: + + - ``pytest-xyz-admin`` team, with full administration rights to + ``pytest-dev/pytest-xyz``. + - ``pytest-xyz-developers`` team, with write access to + ``pytest-dev/pytest-xyz``. + +* ``joedoe`` is invited to the ``pytest-xyz-admin`` team; + +* After accepting the invitation, ``joedoe`` transfers the repository from its + original location to ``pytest-dev/pytest-xyz`` (A nice feature is that GitHub handles URL redirection from + the old to the new location automatically). + +* ``joedoe`` is free to add any other collaborators to the + ``pytest-xyz-developers`` team as desired. + +The ``pytest-dev/Contributors`` team has write access to all projects, and +every project administrator is in it. We recommend that each plugin has at least three +people who have the right to release to PyPI. + +Repository owners can be assured that no ``pytest-dev`` administrator will ever make +releases of your repository or take ownership in anyway, except in rare cases +where someone becomes unresponsive after months. As stated, the +objective is to share maintenance and avoid "plugin-abandon". + + .. _`pull requests`: .. _pull-requests: Preparing Pull Requests on GitHub --------------------------------- +There's an excellent tutorial on how Pull Requests work in the +`GitHub Help Center `_ + + .. 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 From 688622f5cfa6568d28b1b0940ec2f34bfb9397f7 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Fri, 19 Feb 2016 18:23:38 -0200 Subject: [PATCH 2/2] Code review suggestions --- CONTRIBUTING.rst | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index bd2bad34b..75ee3ec32 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -17,7 +17,7 @@ Feature requests and feedback 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 `__ and: +`submit them as issues `_ and: * Explain in detail how they should work. * Keep the scope as narrow as possible. This will make it easier to implement. @@ -109,7 +109,7 @@ 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. + prefixed name, version number, authors, short and long description. - a ``tox.ini`` for running tests using `tox `_. @@ -119,14 +119,13 @@ the following: - 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. +- an issue tracker for bug reports and enhancement requests. If no contributor strongly objects and two agree, the repository can then be transferred to the ``pytest-dev`` organisation. Here's a rundown of how a repository transfer usually proceeds -(using a repository named ``joedoe/pytest-xyz`` as an example): +(using a repository named ``joedoe/pytest-xyz`` as example): * One of the ``pytest-dev`` administrators creates: @@ -142,16 +141,16 @@ Here's a rundown of how a repository transfer usually proceeds the old to the new location automatically). * ``joedoe`` is free to add any other collaborators to the - ``pytest-xyz-developers`` team as desired. + ``pytest-xyz-admin`` or ``pytest-xyz-developers`` team as desired. The ``pytest-dev/Contributors`` team has write access to all projects, and every project administrator is in it. We recommend that each plugin has at least three people who have the right to release to PyPI. Repository owners can be assured that no ``pytest-dev`` administrator will ever make -releases of your repository or take ownership in anyway, except in rare cases -where someone becomes unresponsive after months. As stated, the -objective is to share maintenance and avoid "plugin-abandon". +releases of your repository or take ownership in any way, except in rare cases +where someone becomes unresponsive after months of contact attempts. +As stated, the objective is to share maintenance and avoid "plugin-abandon". .. _`pull requests`: