From d5b191415851374f4aa7e8056753b742679e2c4c Mon Sep 17 00:00:00 2001 From: Stefan Wojcik Date: Sun, 26 Feb 2017 13:35:03 -0500 Subject: [PATCH] include supported mongodb ver info in the readme [ci skip] --- .travis.yml | 2 ++ CONTRIBUTING.rst | 29 +++++++++++++++++++---------- README.rst | 43 +++++++++++++++++++++++++------------------ 3 files changed, 46 insertions(+), 28 deletions(-) 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+.