How to contribute to Werkzeug
=============================

Thank you for considering contributing to Werkzeug!


Support questions
-----------------

Please, don't use the issue tracker for this. Use one of the following
resources for questions about your own code:

- The IRC channel ``#pocoo`` on FreeNode.
- The IRC channel ``#python`` on FreeNode for more general questions.
- 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 werkzeug {search term, exception message, etc.}``.
  Be sure to include a `minimal, complete, and verifiable example`_.


Reporting issues
----------------

- Describe what you expected to happen.
- If possible, include a `minimal, complete, and verifiable 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 Werkzeug versions. If possible, check if
  this issue is already fixed in the repository.


Submitting patches
------------------

- 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.
- Follow the `PEP8`_ style guide.


First time setup
~~~~~~~~~~~~~~~~

- Download and install the `latest version of git`_.
- Configure git with your `username`_ and `email`_::

        git config --global user.name 'your name'
        git config --global user.email 'your email'

- Make sure you have a `GitHub account`_.
- Fork Werkzeug to your GitHub account by clicking the `Fork`_ button.
- `Clone`_ your GitHub fork locally::

        git clone https://github.com/{username}/werkzeug
        cd werkzeug

- Add the main repository as a remote to update later::

        git remote add pallets https://github.com/pallets/werkzeug
        git fetch pallets

- Create a virtualenv::

        python3 -m venv venv
        . venv/bin/activate
        # or "venv\Scripts\activate" on Windows

- Install Werkzeug in editable mode with development dependencies::

        pip install -e ".[dev]"


Start coding
~~~~~~~~~~~~

- Create a branch to identify the issue you would like to work on (e.g.
  ``2287-dry-test-suite``)
- Using your favorite editor, make your changes, `committing as you go`_.
- Follow the `PEP8`_ style guide.
- 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 GitHub and `create a pull request`_.
- Celebrate 🎉


Running the tests
~~~~~~~~~~~~~~~~~

Run the basic test suite with::

    pytest

This only runs the tests for the current environment. Whether this is
relevant depends on which part of Werkzeug you're working on. Travis-CI
will run the full suite when you submit your pull request.

The full test suite takes a long time to run because it tests multiple
combinations of Python and dependencies. You need to have Python 2.7,
3.4, 3.5, 3.6, and PyPy 2.7, as well as Redis and memcached installed to
run all of the environments. Then run::

    tox


Running test coverage
~~~~~~~~~~~~~~~~~~~~~

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 on the terminal and as an interactive HTML document::

    coverage run -m pytest
    coverage report
    coverage html
    # then open htmlcov/index.html

Read more about `coverage`_.

Running the full test suite with ``tox`` will combine the coverage
reports from all runs.


.. _Stack Overflow: https://stackoverflow.com/questions/tagged/werkzeug?sort=linked
.. _minimal, complete, and verifiable example: https://stackoverflow.com/help/mcve
.. _GitHub account: https://github.com/join
.. _latest version of git: https://git-scm.com/downloads
.. _username: https://help.github.com/articles/setting-your-username-in-git/
.. _email: https://help.github.com/articles/setting-your-email-in-git/
.. _Fork: https://github.com/pallets/werkzeug/pull/2305#fork-destination-box
.. _Clone: https://help.github.com/articles/fork-a-repo/#step-2-create-a-local-clone-of-your-fork
.. _committing as you go: https://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html#commit-your-changes
.. _PEP8: https://pep8.org/
.. _create a pull request: https://help.github.com/articles/creating-a-pull-request/
.. _coverage: https://coverage.readthedocs.io
