starlette/CONTRIBUTING.md

Contributing to Starlette

The Starlette team happily welcomes contributions. This document will help you get ready to contribute to Starlette!

NOTE: before writing any code, please first open an issue and discuss your ideas with the maintainers.

Setting up the repository

1. Fork the repo.
2. Clone your fork on your local computer: git clone https://github.com/<username>/starlette.git.
3. Install Starlette locally and run the tests (see next sections).
4. Create a branch for your work, e.g. git checkout -b fix-some-bug.
5. Remember to include tests and documentation updates if applicable.
6. Once ready, push to your remote: git push origin fix-some-bug.
7. Open a PR on the main repo.

Install

• Make sure you are using a compatible Python version, as specified in our README.
• Create a virtual environment and install project dependencies:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

• Install an editable version of the project: pip install -e . (see Editable Installs in the pip docs).

Running the tests

The tests are written using pytest and located in the tests/ directory.

Note: tests should be run before making any changes to the code in order to make sure that everything is running as expected.

We provide a stand-alone test script to run tests in a reliable manner. Run it with:

./scripts/test

By default, tests involving a database are excluded. To include them, set the STARLETTE_TEST_DATABASE environment variable to the URL of a PostgreSQL database, e.g.:

export STARLETTE_TEST_DATABASE="postgresql://localhost/starlette"

Linting

We use Black as a code formatter. To run it along with a few other linting tools, we provide a stand-alone linting script:

./scripts/lint

If linting has anything to say about the code, it will format it in-place.

To keep the code style consistent, you should apply linting before committing.

Documentation

The documentation is built with MkDocs, a Markdown-based documentation site generator.

To run the docs site in hot-reload mode (useful when editing the docs), run $ mkdocs serve in the project root directory.

For your information, the docs site configuration is located in the mkdocs.yml file.

Please refer to the MkDocs docs for more usage information, including how to add new pages.