Contributing guide

MongoEngine has a large community and contributions are always encouraged. Contributors can be as simple as the documentation, as well as complete new features and integrations. Please read these guidelines before sending a pull request.

Bugfixes and new features

Before starting to write code, look for existing tickets or create one for your specific issue or feature request. That way you avoid working on something that has already been addressed.

For new integrations do your best to make integration optional, to lower user opportunity to exclude additional dependencies, in case when user do not need integration or feature.

Supported interpreters

Flask-MongoEngine supports CPython 3.7 and newer, PyPy 3.7 and newer. Language features not supported by all interpreters can not be used.

Running tests

All development requirements, except docker are included in package extra options dev. So, to install full development environment you need just run package with all related options installation.

Our local test environment is based on docker and nox to test project on real database engine and not use any database mocking, as such mocking can raise unexpected behaviour, that is not seen in real database engines.

Before running tests, please ensure that real database not launched on local port 27017, otherwise tests will fail. If you want to run tests with local launched database engine, run tests in non-interactive mode (see below). In this case docker cannot be used at all.

We do not include docker python package to requirements, to exclude harming local developer's setups, if docker installed in non-recommended/other way.

To run minimum amount of required tests with docker, use:

nox

To run minimum amount of required tests with local database, use:

nox --non-interactive

To run one or mode nox sessions only, use -s option. For example to run only documentation and linting tests, run:

nox -s documentation tests lint

In some cases you will want to bypass arguments to pytest itself, to run single test or single test file. It is easy to do, everything after double dash will be bypassed to pytest directly. For example, to run test__normal_command__logged test only, use:

nox -s test__normal_command__logged

Setting up the code for local development and tests

Fork the flask-mongoengine repo on GitHub.

Clone your fork locally:

git clone git@github.com:your_name_here/flask-mongoengine.git

Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development with all required development and testing dependencies (except docker):
```
cd flask-mongoengine/
# With all development and package requirements, except docker
pip install -e .[wtf,toolbar,dev]
```
Create a branch for local development:
```
git checkout -b name-of-your-bugfix-or-feature
```
Now you can make your changes locally.
When you're done making changes, check that your changes pass the tests and lint check:
```
nox
```
Please note that nox run lint and documentation builds check automatically, since we have a nox environment for it. During lint check, the most common issues will be fixed automatically, so in case of failed status, firstly just try to rerun check again. If issue is not fixed automatically, check nox.log.
Ensure that your feature or content is fully covered by tests. Check report after regular nox run.
Setup pre-commit git hook before adding any commits. This will ensure the 95% of linting issues. Otherwise, GitHub CI/CD pipeline may fail. This is linting double check (same as lint) and will run always, even if you forgot to run tests before commit:
```
pre-commit install
```

Commit your changes and push your branch to GitHub:

git add .
git commit -m "Your detailed description of your changes."
git push origin name-of-your-bugfix-or-feature

Submit a pull request through the GitHub website.

Interactive documentation development

Our nox configuration include special session for simplifying documentation development. When launched, documentation will be re-rendered after any saved code/documentation files changes. To use this session, after local environment setup, just run:

nox -s docs

Rendered documentation will be available under: http://localhost:9812/

Style guide

General guidelines

Avoid backward breaking changes if at all possible.
Avoid mocking of external libraries. Mocking allowed only in tests.
Avoid complex structures, for complex classes/methods/functions try to separate to little objects, to simplify code reuse and testing.
Avoid code duplications, try to extract duplicate code to function. (Code duplication in tests is allowed.)
Write docstrings for new classes and methods.
Write tests and make sure they pass.
Add yourself to AUTHORS.md.

Code style guide

Docstrings are using RST format. Developer encouraged to include any significant information to docstrings.
Developers are encouraged to include typing information in functions signatures.
Developers should avoid including typing information to docstrings, if possible.
Developers should avoid including typing information to docstrings and comments in same objects, to avoid rendering conflicts.
Code formatting is completely done by black and following black's style implementation of PEP8. Target python version is the lowest supported version.
Code formatting should be done before passing any new merge requests.
Code style should use f-strings if possible, exceptional can be made for expensive debug level logging statements.

Documentation style guide

Documentation should use Markdown as main format, including Rest syntax blocks inside are allowed. Exceptional is API auto modules documents. Our documentation engine support MyST markdown extensions.
Documentation should use same 88 string length requirements, as code. Strings can be larger for cases, when last word/statement is any kind of link (either to class/function/attribute or web link).
Weblinks should be placed at the end of document, to make documentation easy readable without rendering (in editor).
Docs formatting should be checked and formatted with pre-commit plugin before submitting.

CI/CD testing

All tests are run on GitHub Actions and any pull requests are automatically tested for full range of supported Flask, mongoengine, python and mongodb versions. Any pull requests without tests will take longer to be integrated and might be refused.

← Previous Next →