Merged contributing-community into default

doc/en/plugins.txt

@@ -1,7 +1,7 @@
 .. _plugins:
 
 Working with plugins and conftest files
-=============================================
+=======================================
 
 ``pytest`` implements all aspects of configuration, collection, running and reporting by calling `well specified hooks`_.  Virtually any Python module can be registered as a plugin.  It can implement any number of hook functions (usually two or three) which all have a ``pytest_`` prefix, making hook functions easy to distinguish and find.  There are three basic location types:
 
@@ -16,7 +16,7 @@ Working with plugins and conftest files
 .. _`conftest`:
 
 conftest.py: local per-directory plugins
---------------------------------------------------------------
+----------------------------------------
 
 local ``conftest.py`` plugins contain directory-specific hook
 implementations.  Session and test running activities will
@@ -55,7 +55,7 @@ Here is how you might run it::
 .. _`extplugins`:
 
 Installing External Plugins / Searching
-------------------------------------------------------
+---------------------------------------
 
 Installing a plugin happens through any usual Python installation
 tool, for example::
@@ -119,8 +119,42 @@ You may also discover more plugins through a `pytest- pypi.python.org search`_.
 .. _`available installable plugins`:
 .. _`pytest- pypi.python.org search`: http://pypi.python.org/pypi?%3Aaction=search&term=pytest-&submit=search
 
+
+External plugin development
+---------------------------
+
+Pytest community cares about pytest users, in particular, it's crucial for the community
+to keep all pieces of the pytest ecosystem well supported. External plugins are important for
+pytest users, as they implement many useful, and sometimes critical features which the pytest core does
+not implement.
+
+To simplify the plugin development and/or support, it was decided to create teams(companies) on popular code hosting
+services (at the moment it's github and bitbucket):
+
+* `<https://github.com/pytest-dev>`_:
+    probably the most popular hosting for pytest plugins
+    the name ``pytest-dev`` is choosen because ``pytest`` was already taken by
+    some unknown person, who's not active on the github or just doesn't check the email used to register
+    that organization.
+* `<https://bitbucket.org/pytest-dev>`_:
+    pytest is hosted on the bitbucket, also a lot of pytest plugins are hosted there.
+
+More code hosting services can be added in the future.
+
+Community encourages pytest plugin developers to move their plugins under those organizations (eg transfer ownership),
+paying with a better support, faster feedback, better discoverability, etc.
+
+Generic workflow of the ownership transfer looks like:
+
+* If not a member already, developer asks for a membership in the `pytest plugin developers community` organizations listed above, sending an email to `<pytest-dev@python.org>`_.
+
+* Developer transfers the ownership of his plugin repository to the organization listed above.
+
+* Existing organization members will make sure proper write permissions are set up for developer who transfered the ownership to the organization.
+
+
 Writing a plugin by looking at examples
-------------------------------------------------------
+---------------------------------------
 
 .. _`Distribute`: http://pypi.python.org/pypi/distribute
 .. _`setuptools`: http://pypi.python.org/pypi/setuptools
@@ -138,7 +172,7 @@ to extend and add functionality.
 .. _`setuptools entry points`:
 
 Making your plugin installable by others
------------------------------------------------
+----------------------------------------
 
 If you want to make your plugin externally available, you
 may define a so-called entry point for your distribution so
@@ -169,10 +203,11 @@ If a package is installed this way, ``pytest`` will load
 ``myproject.pluginmodule`` as a plugin which can define
 `well specified hooks`_.
 
+
 .. _`pluginorder`:
 
 Plugin discovery order at tool startup
---------------------------------------------
+--------------------------------------
 
 ``pytest`` loads plugin modules at tool startup in the following way:
 
@@ -199,7 +234,7 @@ Plugin discovery order at tool startup
 
 
 Requiring/Loading plugins in a test module or conftest file
--------------------------------------------------------------
+-----------------------------------------------------------
 
 You can require plugins in a test module or a conftest file like this::
 
@@ -214,7 +249,7 @@ which will import the specified module as a ``pytest`` plugin.
 
 
 Accessing another plugin by name
---------------------------------------------
+--------------------------------
 
 If a plugin wants to collaborate with code from
 another plugin it can obtain a reference through
@@ -230,7 +265,7 @@ the ``--traceconfig`` option.
 .. _`findpluginname`:
 
 Finding out which plugins are active
-----------------------------------------------------------------------------
+------------------------------------
 
 If you want to find out which plugins are active in your
 environment you can type::
@@ -244,7 +279,7 @@ and their names. It will also print local plugins aka
 .. _`cmdunregister`:
 
 Deactivating / unregistering a plugin by name
-----------------------------------------------------------------------------
+---------------------------------------------
 
 You can prevent plugins from loading or unregister them::
 
@@ -257,7 +292,7 @@ how to obtain the name of a plugin.
 .. _`builtin plugins`:
 
 pytest default plugin reference
-====================================
+===============================
 
 
 You can find the source code for the following plugins
@@ -291,10 +326,10 @@ in the `pytest repository <http://bitbucket.org/hpk42/pytest/>`_.
 .. _`well specified hooks`:
 
 pytest hook reference
-====================================
+=====================
 
 Hook specification and validation
------------------------------------------
+---------------------------------
 
 ``pytest`` calls hook functions to implement initialization, running,
 test execution and reporting.  When ``pytest`` loads a plugin it validates
@@ -305,7 +340,7 @@ by simply not specifying them.  If you mistype argument names or the
 hook name itself you get an error showing the available arguments.
 
 Initialization, command line and configuration hooks
---------------------------------------------------------------------
+----------------------------------------------------
 
 .. currentmodule:: _pytest.hookspec
 
@@ -319,7 +354,7 @@ Initialization, command line and configuration hooks
 .. autofunction:: pytest_unconfigure
 
 Generic "runtest" hooks
-------------------------------
+-----------------------
 
 All runtest related hooks receive a :py:class:`pytest.Item` object.
 
@@ -339,7 +374,7 @@ The :py:mod:`_pytest.terminal` reported specifically uses
 the reporting hook to print information about a test run.
 
 Collection hooks
-------------------------------
+----------------
 
 ``pytest`` calls the following hooks for collecting files and directories:
 
@@ -359,7 +394,7 @@ items, delete or otherwise amend the test items:
 .. autofunction:: pytest_collection_modifyitems
 
 Reporting hooks
-------------------------------
+---------------
 
 Session related reporting hooks:
 
@@ -375,7 +410,7 @@ test execution:
 
 
 Debugging/Interaction hooks
---------------------------------------
+---------------------------
 
 There are few hooks which can be used for special
 reporting or interaction with exceptions:
@@ -468,7 +503,7 @@ that result, however.
 
 
 Reference of objects involved in hooks
-===========================================================
+======================================
 
 .. autoclass:: _pytest.config.Config()
     :members: