update contributing guide (#1584)

1 files changed, 185 insertions, 39 deletions

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index c962238..7ec5bc9 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -1,66 +1,212 @@
-==========================
 How to contribute to Click
 ==========================
 
-Thanks for considering contributing to Click.
+Thank you for considering contributing to Click!
+
 
 Support questions
-=================
+-----------------
+
+Please, don't use the issue tracker for this. The issue tracker is a
+tool to address bugs and feature requests in Click itself. Use one of
+the following resources for questions about using Click or issues with
+your own code:
+
+-   The ``#get-help`` channel on our Discord chat:
+    https://discord.gg/t6rrQZH
+-   The mailing list flask@python.org for long term discussion or larger
+    issues.
+-   Ask on `Stack Overflow`_. Search with Google first using:
+    ``site:stackoverflow.com python click {search term, exception message, etc.}``
 
-Please, don't use the issue tracker for this. Check whether the
-``#pocoo`` IRC channel on Freenode can help with your issue. If your problem
-is not strictly Click-specific, ``#python`` on Freenode is generally more
-active.  Also try searching or asking on `Stack Overflow`_ with the
-``python-click`` tag.
+.. _Stack Overflow: https://stackoverflow.com/questions/tagged/python-click?sort=linked
 
-.. _Stack Overflow: https://stackoverflow.com/questions/tagged/python-click?sort=votes
 
 Reporting issues
-================
+----------------
 
-- Under which versions of Python does this happen? This is even more important
-  if your issue is encoding related.
+Include the following information in your post:
+
+-   Describe what you expected to happen.
+-   If possible, include a `minimal reproducible example`_ to help us
+    identify the issue. This also helps check that the issue is not with
+    your own code.
+-   Describe what actually happened. Include the full traceback if there
+    was an exception.
+-   List your Python and Click. If possible, check if this issue is
+    already fixed in the latest releases or the latest code in the
+    repository.
+
+.. _minimal reproducible example: https://stackoverflow.com/help/minimal-reproducible-example
 
-- Under which versions of Click does this happen? Check if this issue is fixed
-  in the repository.
 
 Submitting patches
-==================
+------------------
+
+If there is not an open issue for what you want to submit, prefer
+opening one for discussion before working on a PR. You can work on any
+issue that doesn't have an open PR linked to it or a maintainer assigned
+to it. These show up in the sidebar. No need to ask if you can work on
+an issue that interests you.
+
+Include the following in your patch:
+
+-   Use `Black`_ to format your code. This and other tools will run
+    automatically if you install `pre-commit`_ using the instructions
+    below.
+-   Include tests if your patch adds or changes code. Make sure the test
+    fails without your patch.
+-   Update any relevant docs pages and docstrings. Docs pages and
+    docstrings should be wrapped at 72 characters.
+-   Add an entry in ``CHANGES.rst``. Use the same style as other
+    entries. Also include ``.. versionchanged::`` inline changelogs in
+    relevant docstrings.
+
+.. _Black: https://black.readthedocs.io
+.. _pre-commit: https://pre-commit.com
+
+
+First time setup
+~~~~~~~~~~~~~~~~
+
+-   Download and install the `latest version of git`_.
+-   Configure git with your `username`_ and `email`_.
+
+    .. code-block:: text
+
+        $ git config --global user.name 'your name'
+        $ git config --global user.email 'your email'
+
+-   Make sure you have a `GitHub account`_.
+-   Fork Click to your GitHub account by clicking the `Fork`_ button.
+-   `Clone`_ the main repository locally.
+
+    .. code-block:: text
+
+        $ git clone https://github.com/pallets/click
+        $ cd click
+
+-   Add your fork as a remote to push your work to. Replace
+    ``{username}`` with your username.
+
+    .. code-block:: text
+
+        git remote add fork https://github.com/{username}/click
+
+-   Create a virtualenv.
+
+    .. code-block:: text
+
+        $ python3 -m venv env
+        $ . env/bin/activate
+
+    On Windows, activating is different.
+
+    .. code-block:: text
+
+        > env\Scripts\activate
+
+-   Install Click in editable mode with development dependencies.
+
+    .. code-block:: text
+
+        $ pip install -e . -r requirements/dev.txt
+
+-   Install the pre-commit hooks.
+
+    .. code-block:: text
+
+        $ pre-commit install
+
+.. _latest version of git: https://git-scm.com/downloads
+.. _username: https://help.github.com/en/articles/setting-your-username-in-git
+.. _email: https://help.github.com/en/articles/setting-your-commit-email-address-in-git
+.. _GitHub account: https://github.com/join
+.. _Fork: https://github.com/pallets/click/fork
+.. _Clone: https://help.github.com/en/articles/fork-a-repo#step-2-create-a-local-clone-of-your-fork
+
+
+Start coding
+~~~~~~~~~~~~
+
+-   Create a branch to identify the issue you would like to work on. If
+    you're submitting a bug or documentation fix, branch off of the
+    latest ".x" branch.
+
+    .. code-block:: text
+
+        $ git checkout -b your-branch-name origin/7.x
+
+    If you're submitting a feature addition or change, branch off of the
+    "master" branch.
+
+    .. code-block:: text
+
+        $ git checkout -b your-branch-name origin/master
+
+-   Using your favorite editor, make your changes,
+    `committing as you go`_.
+-   Include tests that cover any code changes you make. Make sure the
+    test fails without your patch. Run the tests as described below.
+-   Push your commits to your fork on GitHub and
+    `create a pull request`_. Link to the issue being addressed with
+    ``fixes #123`` in the pull request.
+
+    .. code-block:: text
+
+        $ git push --set-upstream fork your-branch-name
+
+.. _committing as you go: https://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html#commit-your-changes
+.. _create a pull request: https://help.github.com/en/articles/creating-a-pull-request
+
+
+Running the tests
+~~~~~~~~~~~~~~~~~
+
+Run the basic test suite with pytest.
+
+.. code-block:: text
+
+    $ pytest
+
+This runs the tests for the current environment, which is usually
+sufficient. CI will run the full suite when you submit your pull
+request. You can run the full test suite with tox if you don't want to
+wait.
+
+.. code-block:: text
+
+    $ tox
 
-- Include tests if your patch is supposed to solve a bug, and explain clearly
-  under which circumstances the bug happens. Make sure the test fails without
-  your patch.
 
-- Try to follow `PEP8 <http://legacy.python.org/dev/peps/pep-0008/>`_, but you
-  may ignore the line-length-limit if following it would make the code uglier.
+Running test coverage
+~~~~~~~~~~~~~~~~~~~~~
 
-- For features: Consider whether your feature would be a better fit for an
-  `external package <https://click.palletsprojects.com/en/7.x/contrib/>`_
+Generating a report of lines that do not have test coverage can indicate
+where to start contributing. Run ``pytest`` using ``coverage`` and
+generate a report.
 
-- For docs and bug fixes: Submit against the latest maintenance branch instead of master!
+.. code-block:: text
 
-- Non docs or text related changes need an entry in ``CHANGES.rst``,
-  and ``.. versionadded`` or ``.. versionchanged`` markers in the docs.
+    $ pip install coverage
+    $ coverage run -m pytest
+    $ coverage html
 
-Running the testsuite
----------------------
+Open ``htmlcov/index.html`` in your browser to explore the report.
 
-You probably want to set up a `virtualenv
-<https://virtualenv.readthedocs.io/en/latest/index.html>`_.
+Read more about `coverage <https://coverage.readthedocs.io>`__.
 
-The minimal requirement for running the testsuite is ``py.test``.  You can
-install it with::
 
-    pip install pytest
+Building the docs
+~~~~~~~~~~~~~~~~~
 
-Then you can run the testsuite with::
+Build the docs in the ``docs`` directory using Sphinx.
 
-    py.test
+.. code-block:: text
 
-For a more isolated test environment, you can also install ``tox`` instead of
-``pytest``. You can install it with::
+    $ cd docs
+    $ make html
 
-    pip install tox
+Open ``_build/html/index.html`` in your browser to view the docs.
 
-The ``tox`` command will then run all tests against multiple combinations of
-Python versions and dependency versions.
+Read more about `Sphinx <https://www.sphinx-doc.org/en/stable/>`__.