diff --git a/.travis.yml b/.travis.yml
index 482318e5..47448950 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -7,6 +7,8 @@
# * MongoDB v3.0 is tested against PyMongo v3.x.
# * MongoDB v2.6 is currently the "main" version tested against Python v2.7,
# v3.5, PyPy & PyPy3, and PyMongo v2.7, v2.8 & v3.x.
+#
+# Reminder: Update README.rst if you change MongoDB versions we test.
language: python
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 2668499c..5707886b 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -29,19 +29,20 @@ 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 `_
+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
+`_
Testing
-------
All tests are run on `Travis `_
-and any pull requests are automatically tested by Travis. Any pull requests
-without tests will take longer to be integrated and might be refused.
+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 PullRequest if you don't know
+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.
@@ -49,13 +50,18 @@ 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 setup.py nosetests``
from the cmd line to run the test suite).
-- Ensure tests pass on every Python and PyMongo versions.
- You can test on these versions locally by executing ``tox``
-- Add enhancements or problematic bug fixes to docs/changelog.rst
+- 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 :)
Documentation
@@ -69,3 +75,6 @@ just make your changes to the inline documentation of the appropriate
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`` package.
diff --git a/README.rst b/README.rst
index adfa0c71..008b182c 100644
--- a/README.rst
+++ b/README.rst
@@ -19,23 +19,24 @@ MongoEngine
About
=====
MongoEngine is a Python Object-Document Mapper for working with MongoDB.
-Documentation available at https://mongoengine-odm.readthedocs.io - there is currently
-a `tutorial `_, a `user guide
-`_ and an `API reference
-`_.
+Documentation is available at https://mongoengine-odm.readthedocs.io - there
+is currently a `tutorial `_,
+a `user guide `_, and
+an `API reference `_.
Installation
============
We recommend the use of `virtualenv `_ and of
`pip `_. You can then use ``pip install -U mongoengine``.
-You may also have `setuptools `_ and thus
-you can use ``easy_install -U mongoengine``. Otherwise, you can download the
+You may also have `setuptools `_
+and thus you can use ``easy_install -U mongoengine``. Otherwise, you can download the
source from `GitHub `_ and run ``python
setup.py install``.
Dependencies
============
-All of the dependencies can easily be installed via `pip `_. At the very least, you'll need these two packages to use MongoEngine:
+All of the dependencies can easily be installed via `pip `_.
+At the very least, you'll need these two packages to use MongoEngine:
- pymongo>=2.7.1
- six>=1.10.0
@@ -48,10 +49,6 @@ If you need to use an ``ImageField`` or ``ImageGridFsProxy``:
- Pillow>=2.0.0
-If you want to generate the documentation (e.g. to contribute to it):
-
-- sphinx
-
Examples
========
Some simple examples of what MongoEngine code looks like:
@@ -112,9 +109,9 @@ Tests
To run the test suite, ensure you are running a local instance of MongoDB on
the standard port and have ``nose`` installed. Then, run: ``python setup.py nosetests``.
-To run the test suite on every supported Python version and every supported PyMongo version,
-you can use ``tox``.
-tox and each supported Python version should be installed in your environment:
+To run the test suite on every supported Python and PyMongo version, you can
+use ``tox``. You'll need to make sure you have each supported Python version
+installed in your environment and then:
.. code-block:: shell
@@ -123,13 +120,16 @@ tox and each supported Python version should be installed in your environment:
# Run the test suites
$ tox
-If you wish to run one single or selected tests, use the nosetest convention. It will find the folder,
-eventually the file, go to the TestClass specified after the colon and eventually right to the single test.
-Also use the -s argument if you want to print out whatever or access pdb while testing.
+If you wish to run a subset of tests, use the nosetest convention:
.. code-block:: shell
- $ python setup.py nosetests --tests tests/fields/fields.py:FieldTest.test_cls_field -s
+ # Run all the tests in a particular test file
+ $ python setup.py nosetests --tests tests/fields/fields.py
+ # Run only particular test class in that file
+ $ python setup.py nosetests --tests tests/fields/fields.py:FieldTest
+ # Use the -s option if you want to print some debug statements or use pdb
+ $ python setup.py nosetests --tests tests/fields/fields.py:FieldTest -s
Community
=========
@@ -141,3 +141,10 @@ Community
Contributing
============
We welcome contributions! See the `Contribution guidelines `_
+
+Supported MongoDB Versions
+==========================
+MongoEngine is currently tested against MongoDB v2.4, v2.6, and v3.0. Future
+versions should be supported as well, but aren't actively tested at the moment.
+Make sure to open an issue or submit a pull request if you experience any
+problems with MongoDB v3.2+.