Contributing to Mangum
Hello. Contributions to this project are highly encouraged and appreciated. This document will outline some general guidelines for how to get started.
- Creating a pull request
- Setting up the repository
- Developing the project locally
- Using the issue tracker
- Technical support
- Feature requests
Creating a pull request
Non-trivial changes, especially those that could impact existing behaviour, should have an associated issue created for discussion. An issue isn't strictly required for larger changes, but it can be helpful to discuss first.
Minor changes generally should not require a new issue and can be explained in the pull request description.
Setting up the repository
To create a pull request, you must first fork the repository in GitHub, then clone the fork locally.
git clone email@example.com:<YOUR-USERNAME>/mangum.git
Then add the upstream remote to keep the forked repo in sync with the original.
cd mangum git remote add upstream git://github.com/jordaneremieff/mangum.git git fetch upstream
Then to keep in sync with changes in the primary repository, you pull the upstream changes into your local fork.
git pull upstream main
Developing the project locally
There are a few scripts in place to assist with local development, the following scripts are located in the
Running the setup script will create a local Python virtual environment. It assumes that
python3.7 is available in the path and will install the development dependencies located in
Alternatively, you may create a virtual environment and install the requirements manually:
python -m venv venv . venv/bin/active pip install -r requirements.txt
This environment is used to run the tests. Python versions 3.6, 3.7, and 3.8 are supported.
The test script will run all the test cases with PyTest using the path for the virtual environment created in the setup step (above).
It also runs Coverage to produce a code coverage report.
The coverage script is intended to fail under 100% test coverage, but this is not a strict requirement for contributions. Generally speaking at least one test should be included in a PR, but it is okay to use
# pragma: no cover comments in the code to exclude specific coverage cases from the build.
Code style and formatting
Black formatting is required for all files with a maximum line-length of
88 (black's default) and double-quotes
" are preferred over single-quotes
', otherwise there aren't specific style guidelines.
Static type checking
Mypy is used to handle static type checking in the build, and type annotations should be included when making changes or additions to the code. However, it is okay to use
# type: ignore comments when it is unclear what type to use, or if the annotation required to pass the type checker significantly decreases readability.
Using the issue tracker
The issue tracker can be used for different types of discussion, but it is mainly intended for items that are relevant to this project specifically.
Here are a few things you might consider before opening a new issue:
Is this covered in the documentation?
Is there already a related issue in the tracker?
Is this a problem related to Mangum itself or a third-party dependency?
It may still be perfectly valid to open an issue if one or more of these is true, but thinking about these questions might help reveal an existing answer sooner.
You may run into problems running Mangum that are related to a deployment tool (e.g. Serverless Framework), an ASGI framework (e.g. FastAPI), or some other external dependency. It is okay to use the tracker to resolve these kinds of issues, but keep in mind that this project does not guaruntee support for all the features of any specific ASGI framework or external tool.
Note: These issues will typlically be closed, but it is fine to continue discussion on a closed issue. These issues will be re-opened only if a problem is discovered in Mangum itself.
This project is intended to be small and focused on providing an adapter class for ASGI applications deployed in AWS Lambda. Feature requests related to this use-case will generally be considered, but larger features that increase the overall scope of Mangum are less likely to be included.
If you have a large feature request, please make an issue with sufficient detail and it can be discussed. Some feature requests may end up being rejected initially and re-considered later.