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 env
. 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 all supported
CPython and PyPy versions installed to run all of the environments. ::
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