Fetching contributors…
Cannot retrieve contributors at this time
97 lines (75 sloc) 3.37 KB

Contributing To The Project

The best way to contribute changes to IMAPClient is to fork the official repository on Github, make changes in a branch in your personal fork and then submit a pull request.

Discussion on the mailing list before undertaking development is highly encouraged for potentially major changes.

Although not essential, it will make the project maintainer a much happier person if change submissions include appropriate updates to unit tests and the live tests. Please ask if you're unsure how of how the tests work.

Please read on if you plan on submitting changes to IMAPClient.

Source Code

The official source code repository for IMAPClient can be found on Github at:

Any major feature work will also be found as branches of this repository.


[Note that the branching scheme discussed here started to be used as of the 0.9.2 release of IMAPClient]

The project uses two named branches: default and stable. New feature development will always happen on the default branch.

The stable branch will always reflect the last released version. Small bug fixes to the stable release will occur on this branch and should be merged back in the the default branch.

Releases will always be created from the stable branch. Before a major release changes will be merged from the default branch to the stable branch.

Release Tags

Each released version is available in the IMAPClient repository as a Git tag (e.g. "0.9.1"). Release tags will always be created on the stable branch (as described above).

Unit Tests

There are comprehensive unit tests for the server response parser and a number of other parts of the code. These tests use the unittest2 package which is also included as the standard unittest package in Python 2.7 and 3.2 onwards.

Running Unit Tests

To run the tests run:

python test

from the root of the package source. This will install the Mock package (locally) if it isn't already installed as it is required for many of the tests.

Where unittest2 is included in the standard library (eg. Python 2.7 and 3.2+) you can also run all unit tests like this (from the root directory of the IMAPClient source):

python -m unittest discover

Alternatively, if unittest2 is installed separately use the unit2 script (for Unix-like systems) or the script:

unit2 discover discover

Running the Unit Tests Against Multiple Python Versions

It is possible to run the unit tests against all supported Python versions at once using tox. Once installed, the tox command will use the tox.ini file in the root of the source directory and run the unit tests against the Python versions officially supported by IMAPClient (provided these versions of Python are installed!).

Writing Unit Tests

Protocol level unit tests should not act against a real IMAP server but should use canned data instead. The IMAPClientTest base class should typically be used as the base class for any tests - it provides a mock IMAPClient instance at self.client. See the tests in imapclient/tests/ for examples of how to write unit tests using this approach.