Permalink
Newer
Older
100644 83 lines (67 sloc) 3.57 KB
1
Contributing to MongoEngine
2
===========================
3
4
MongoEngine has a large `community
5
<https://raw.github.com/MongoEngine/mongoengine/master/AUTHORS>`_ and
6
contributions are always encouraged. Contributions can be as simple as
7
minor tweaks to the documentation. Please read these guidelines before
8
sending a pull request.
9
10
Bugfixes and New Features
11
-------------------------
12
13
Before starting to write code, look for existing `tickets
14
<https://github.com/MongoEngine/mongoengine/issues?state=open>`_ or `create one
15
<https://github.com/MongoEngine/mongoengine/issues>`_ for your specific
16
issue or feature request. That way you avoid working on something
17
that might not be of interest or that has already been addressed. If in doubt
18
post to the `user group <http://groups.google.com/group/mongoengine-users>`
19
20
Supported Interpreters
21
----------------------
22
23
MongoEngine supports CPython 2.7 and newer. Language
24
features not supported by all interpreters can not be used.
25
Please also ensure that your code is properly converted by
26
`2to3 <http://docs.python.org/library/2to3.html>`_ for Python 3 support.
27
28
Style Guide
29
-----------
30
31
MongoEngine aims to follow `PEP8 <http://www.python.org/dev/peps/pep-0008/>`_
32
including 4 space indents. When possible we try to stick to 79 character line
33
limits. However, screens got bigger and an ORM has a strong focus on
34
readability and if it can help, we accept 119 as maximum line length, in a
35
similar way as `django does
36
<https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/coding-style/#python-style>`_
37
38
Testing
39
-------
40
41
All tests are run on `Travis <http://travis-ci.org/MongoEngine/mongoengine>`_
42
and any pull requests are automatically tested. Any pull requests without
43
tests will take longer to be integrated and might be refused.
44
45
You may also submit a simple failing test as a pull request if you don't know
Apr 30, 2015
46
how to fix it, it will be easier for other people to work on it and it may get
47
fixed faster.
48
49
General Guidelines
50
------------------
51
52
- Avoid backward breaking changes if at all possible.
53
- If you *have* to introduce a breaking change, make it very clear in your
54
pull request's description. Also, describe how users of this package
55
should adapt to the breaking change in docs/upgrade.rst.
56
- Write inline documentation for new classes and methods.
57
- Write tests and make sure they pass (make sure you have a mongod
58
running on the default port, then execute ``python setup.py nosetests``
59
from the cmd line to run the test suite).
60
- Ensure tests pass on all supported Python, PyMongo, and MongoDB versions.
61
You can test various Python and PyMongo versions locally by executing
62
``tox``. For different MongoDB versions, you can rely on our automated
63
Travis tests.
64
- Add enhancements or problematic bug fixes to docs/changelog.rst.
65
- Add yourself to AUTHORS :)
66
67
Documentation
68
-------------
69
70
To contribute to the `API documentation
71
<http://docs.mongoengine.org/en/latest/apireference.html>`_
72
just make your changes to the inline documentation of the appropriate
73
`source code <https://github.com/MongoEngine/mongoengine>`_ or `rst file
74
<https://github.com/MongoEngine/mongoengine/tree/master/docs>`_ in a
75
branch and submit a `pull request <https://help.github.com/articles/using-pull-requests>`_.
76
You might also use the github `Edit <https://github.com/blog/844-forking-with-the-edit-button>`_
77
button.
78
79
If you want to test your documentation changes locally, you need to install
80
the ``sphinx`` and ``sphinx_rtd_theme`` packages. Once these are installed,
81
go to the ``docs`` directory, run ``make html`` and inspect the updated docs
82
by running ``open _build/html/index.html``.