• Try Starlette andreport bugs/issues you find
• Implement new features
• Review Pull Requests of others
• Write documentation
• Participate in discussions

Reporting Bugs or Other Issues

Found something that Starlette should support?Stumbled upon some unexpected behaviour?

Contributions should generally start out witha discussion.Possible bugs may be raised as a "Potential Issue" discussion, feature requests maybe raised as an "Ideas" discussion. We can then determine if the discussion needsto be escalated into an "Issue" or not, or if we'd consider a pull request.

Try to be more descriptive as you can and in case of a bug report,provide as much information as possible like:

• OS platform
• Python version
• Installed dependencies and versions (python -m pip freeze)
• Code snippet
• Error traceback

You should always try to reduce any examples to thesimplest possible casethat demonstrates the issue.

Development

To start developing Starlette, create afork of theStarlette repository on GitHub.

Then clone your fork with the following command replacingYOUR-USERNAME withyour GitHub username:

$gitclonehttps://github.com/YOUR-USERNAME/starlette

You can now install the project and its dependencies using:

$cdstarlette$scripts/install

Testing and Linting

We use custom shell scripts to automate testing, linting,and documentation building workflow.

To run the tests, use:

$scripts/test

Any additional arguments will be passed topytest. See thepytest documentation for more information.

For example, to run a single test script:

$scripts/testtests/test_application.py

To run the code auto-formatting:

$scripts/lint

Lastly, to run code checks separately (they are also run as part ofscripts/test), run:

$scripts/check

Documenting

Documentation pages are located under thedocs/ folder.

To run the documentation site locally (useful for previewing changes), use:

$scripts/docs

Resolving Build / CI Failures

Once you've submitted your pull request, the test suite will automatically run, and the results will show up in GitHub.If the test suite fails, you'll want to click through to the "Details" link, and try to identify why the test suite failed.

Here are some common ways the test suite can fail:

Check Job Failed

This job failing means there is either a code formatting issue or type-annotation issue.You can look at the job output to figure out why it's failed or within a shell run:

$scripts/check

It may be worth it to run$ scripts/lint to attempt auto-formatting the codeand if that job succeeds commit the changes.

Docs Job Failed

This job failing means the documentation failed to build. This can happen fora variety of reasons like invalid markdown or missing configuration withinmkdocs.yml.

Python 3.X Job Failed

This job failing means the unit tests failed or not all code paths are covered by unit tests.

If tests are failing you will see this message under the coverage report:

=== 1 failed, 435 passed, 1 skipped, 1 xfailed in 11.09s ===

If tests succeed but coverage doesn't reach our current threshold, you will see thismessage under the coverage report:

FAIL Required test coverage of 100% not reached. Total coverage: 99.00%

Releasing

This section is targeted at Starlette maintainers.

Before releasing a new version, create a pull request that includes:

• An update to the changelog:
  • We follow the format fromkeepachangelog.
  • Comparemain with the tag of the latest release, and list all entries that are of interest to our users:
    • Things thatmust go in the changelog: added, changed, deprecated or removed features, and bug fixes.
    • Things thatshould not go in the changelog: changes to documentation, tests or tooling.
    • Try sorting entries in descending order of impact / importance.
    • Keep it concise and to-the-point. 🎯
• A version bump: see__version__.py.

For an example, see#1600.

Once the release PR is merged, create anew release including:

• Tag version like0.13.3.
• Release titleVersion 0.13.3
• Description copied from the changelog.

Once created this release will be automatically uploaded to PyPI.