How to contribute to Flask

Thank you for considering contributing to Flask!

Support questions

Please don't use the issue tracker for this. The issue tracker is a toolto address bugs and feature requests in Flask itself. Use one of thefollowing resources for questions about using Flask or issues with yourown code:

Reporting issues

Include the following information in your post:

  • Describe what you expected to happen.

  • If possible, include aminimal reproducible example to help usidentify the issue. This also helps check that the issue is not withyour own code.

  • Describe what actually happened. Include the full traceback if therewas an exception.

  • List your Python and Flask versions. If possible, check if thisissue is already fixed in the latest releases or the latest code inthe repository.

Submitting patches

If there is not an open issue for what you want to submit, preferopening one for discussion before working on a PR. You can work on anyissue that doesn't have an open PR linked to it or a maintainer assignedto it. These show up in the sidebar. No need to ask if you can work onan issue that interests you.

Include the following in your patch:

  • UseBlack to format your code. This and other tools will runautomatically if you installpre-commit using the instructionsbelow.

  • Include tests if your patch adds or changes code. Make sure the testfails without your patch.

  • Update any relevant docs pages and docstrings. Docs pages anddocstrings should be wrapped at 72 characters.

  • Add an entry inCHANGES.rst. Use the same style as otherentries. Also include..versionchanged:: inline changelogs inrelevant docstrings.

First time setup

  • Download and install thelatest version of git.

  • Configure git with yourusername andemail.

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

  • Make sure you have aGitHub account.

  • Fork Flask to your GitHub account by clicking theFork button.

  • Clone the main repository locally.

    $ git clone https://github.com/pallets/flask$ cd flask

  • Add your fork as a remote to push your work to. Replace{username} with your username. This names the remote "fork", thedefault Pallets remote is "origin".

    $ git remote add fork https://github.com/{username}/flask

  • Create a virtualenv.

    • Linux/macOS

      $ python3 -m venv env$ . env/bin/activate

    • Windows

      > py -3 -m venv env> env\Scripts\activate

  • Upgrade pip and setuptools.

    $ python -m pip install --upgrade pip setuptools

  • Install the development dependencies, then install Flask in editablemode.

    $ pip install -r requirements/dev.txt && pip install -e .

  • Install the pre-commit hooks.

    $ pre-commit install

Start coding

  • Create a branch to identify the issue you would like to work on. Ifyou're submitting a bug or documentation fix, branch off of thelatest ".x" branch.

    $ git fetch origin$ git checkout -b your-branch-name origin/2.0.x

    If you're submitting a feature addition or change, branch off of the"main" branch.

    $ git fetch origin$ git checkout -b your-branch-name origin/main

  • Using your favorite editor, make your changes,committing as you go.

  • Include tests that cover any code changes you make. Make sure thetest fails without your patch. Run the tests as described below.

  • Push your commits to your fork on GitHub andcreate a pull request. Link to the issue being addressed withfixes#123 in the pull request.

    $ git push --set-upstream fork your-branch-name

Running the tests

Run the basic test suite with pytest.

$ pytest

This runs the tests for the current environment, which is usuallysufficient. CI will run the full suite when you submit your pullrequest. You can run the full test suite with tox if you don't want towait.

$ tox

Running test coverage

Generating a report of lines that do not have test coverage can indicatewhere to start contributing. Runpytest usingcoverage andgenerate a report.

$ pip install coverage$ coverage run -m pytest$ coverage html

Openhtmlcov/index.html in your browser to explore the report.

Read more aboutcoverage.

Building the docs

Build the docs in thedocs directory using Sphinx.

$ cd docs$ make html

Open_build/html/index.html in your browser to view the docs.

Read more aboutSphinx.