Find file Copy path
86 lines (70 sloc) 3.76 KB

Contributing to MongoEngine

MongoEngine has a large community and contributions are always encouraged. Contributions can be as simple as minor tweaks to the documentation. 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 might not be of interest or that has already been addressed. If in doubt post to the user group <>

Supported Interpreters

MongoEngine supports CPython 2.7 and newer. Language features not supported by all interpreters can not be used. The codebase is written in python 2 so you must be using python 2 when developing new features. Compatibility of the library with Python 3 relies on the 2to3 package that gets executed as part of the installation build. You should ensure that your code is properly converted by 2to3.

Style Guide

MongoEngine aims to follow PEP8 including 4 space indents. When possible we try to stick to 79 character line limits. However, screens got bigger and an ORM has a strong focus on readability and if it can help, we accept 119 as maximum line length, in a similar way as django does


All tests are run on Travis and any pull requests are automatically tested. Any pull requests without tests will take longer to be integrated and might be refused.

You may also submit a simple failing test as a pull request if you don't know how to fix it, it will be easier for other people to work on it and it may get fixed faster.

General Guidelines

  • Avoid backward breaking changes if at all possible.
  • If you have to introduce a breaking change, make it very clear in your pull request's description. Also, describe how users of this package should adapt to the breaking change in docs/upgrade.rst.
  • Write inline documentation for new classes and methods.
  • Write tests and make sure they pass (make sure you have a mongod running on the default port, then execute python nosetests from the cmd line to run the test suite).
  • Ensure tests pass on all supported Python, PyMongo, and MongoDB versions. You can test various Python and PyMongo versions locally by executing tox. For different MongoDB versions, you can rely on our automated Travis tests.
  • Add enhancements or problematic bug fixes to docs/changelog.rst.
  • Add yourself to AUTHORS :)


To contribute to the API documentation just make your changes to the inline documentation of the appropriate source code or rst file in a branch and submit a pull request. You might also use the github Edit button.

If you want to test your documentation changes locally, you need to install the sphinx and sphinx_rtd_theme packages. Once these are installed, go to the docs directory, run make html and inspect the updated docs by running open _build/html/index.html.