diff options
-rw-r--r-- | CONTRIBUTING.rst | 224 |
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/>`__. |