Contributing¶
The Basics¶
The source code and bug tracker for imapautofiler are hosted on github.
The source code is released under the Apache 2.0 license. All patches should use the same license.
When reporting a bug, please specify the version of imapautofiler you are using.
Message handling rules¶
imapautofiler operation is driven by rules and actions defined in the configuration file.
Each rule is evaluated by a class derived from
Rule
and implemented in
imapautofiler/rules.py
.
A rule must implement the check()
method to support the interface
defined by the abstract base class. The method receives an
email.message.Message instance
containing the message being processed. check()
must return
True
if the rule should be applied to the message, or False
if
it should not.
Each new rule must be handled in the
factory()
function so that when the name of
the rule is encountered the correct rule class is instantiated and
returned.
Message handling actions¶
Each action triggered by a rule is evaluated by a class derived from
Action
and implemented in
imapautofiler/actions.py
.
An action must implement the invoke()
method to support the
interface defined by the abstract base class. The method receives an
IMAPClient
instance (from the imapclient package) connected to
the IMAP server being scanned, a string message ID, and an
email.message.Message instance
containing the message being processed. invoke()
must perform the
relevant operation on the message.
Each new action must be handled in the
factory()
function so that when the name
of the action is encountered the correct action class is instantiated
and returned.
API Documentation¶
Local Test Maildir¶
Use tools/maildir_test_data.py
to create a local test Maildir with
a few sample messages. The script requires several dependencies, so
for convenience there is a tox environment pre-configured to run it in
a virtualenv.
The script requires one argument to indicate the parent directory where the Maildirs should be created.
$ tox -e testdata -- /tmp/testdata
Release Notes¶
This project uses reno for managing release notes. Pull requests with bug fixes and new features should include release notes and documentation updates.
To create a new release note, use the reno new command. Use the version of reno that will be used in the automated documentation build by setting up the documentation build locally using tox.
$ tox -e docs
Then, run the reno command from the virtualenv that tox creates, passing a “slug” containing a summary of the fix or feature.
$ ./.tox/docs/bin/reno new add-reno
no configuration file in: ./releasenotes/config.yaml, ./reno.yaml
Created new notes file in releasenotes/notes/add-reno-65a040ebe662341a.yaml
Finally, edit the file that was created. Fill in the “features” or “fixes” section as appropriate, and remove the rest of the text in the file.
To test the build, you will need to git add the new file, then run tox again.
$ git add releasenotes/notes/add-reno-65a040ebe662341a.yaml
$ tox -e docs
The output will appear in the file doc/build/html/history.html.
Note
Refer to the reno documentation for more details about adding, editing, and managing release notes.