Contributing to Mailman 3
Copyright (C) 2008-2022 by the Free Software Foundation, Inc.
How to contribute
We accept merge requests and bug reports on GitLab. We prefer if every merge request is linked to a bug report, because we can more easily manage the priority of bug reports. For more substantial contributions, we may ask you to sign a copyright assignment to the Free Software Foundation, the owner of the GNU Mailman copyright. If you’d like to jump start your copyright assignment, please contact the GNU Mailman steering committee.
Please read the GNU Mailman Coding Style Guide for required coding style guidelines.
Contact Us
Contributions of code, problem reports, and feature requests are welcome. Please submit bug reports on the Mailman bug tracker at https://gitlab.com/mailman/mailman/issues (you need to have a login on GitLab to do so). You can also send email to the mailman-developers@python.org mailing list (or mailman-users@mailman3.org for usage specific questions).
Get the sources
The Mailman 3 source code is version controlled using Git. You can get a local copy by running this command:
$ git clone https://gitlab.com/mailman/mailman.git
or if you have a GitLab account and prefer ssh:
$ git clone git@gitlab.com:mailman/mailman.git
Testing Mailman 3
To run the Mailman test suite, just use the tox command:
$ tox
tox creates a virtual environment (virtualenv) for you, installs all the dependencies into that virtualenv, and runs the test suite from that virtualenv. By default it does not use the –system-site-packages so it downloads everything from the Python Cheeseshop.
A bare tox
command will try to run several test suites, which might take a
long time, and/or require versions of Python or other components you might not
have installed. You can run tox -l
to list the test suite environments
available. Very often, when you want to run the full test suite in the
quickest manner with components that should be available everywhere, run one
of these commands:
$ tox -e py311-nocov
$ tox -e py39-nocov
You can run individual tests in any given environment by providing additional positional arguments. For example, to run only the tests that match a specific pattern:
$ tox -e py39-nocov -- -P user
You can see all the other arguments supported by the test suite by running:
$ tox -e py39-nocov -- --help
You also have access to the virtual environments created by tox, and you can
use this run the virtual environment’s Python executable, or run the
mailman
command locally, e.g.:
$ .tox/py39-nocov/bin/python
$ .tox/py39-nocov/bin/mailman --help
If you want to set up the virtual environment without running the full test suite, you can do this:
$ tox -e py39-nocov --notest -r
Testing with PostgreSQL and MySQL
By default, the test suite runs with the built-in SQLite database engine. If you want to run the full test suite against the PostgreSQL or MySQL databases, set the database up as described in Setting up your database.
For PostgreSQL, then create a postgres.cfg file any where you want. This
postgres.cfg file will contain the [database]
section for PostgreSQL,
e.g.:
[database]
class: mailman.database.postgresql.PostgreSQLDatabase
url: postgresql://myuser:mypassword@mypghost/mailman
Then run the test suite like so:
$ MAILMAN_EXTRA_TESTING_CFG=/path/to/postgres.cfg tox -e py39-pg
You can combine these ways to invoke Mailman, so if you want to run an individual test against PostgreSQL, you could do:
$ MAILMAN_EXTRA_TESTING_CFG=/path/to/postgres.cfg tox -e py39-pg -- -P user
Note that the path specified in MAILMAN_EXTRA_TESTING_CFG must be an absolute path or some tests will fail.
Building for development
To build Mailman for development purposes, you can create a virtual environment outside of tox. You need to have the virtualenv program installed, or you can use Python 3’s built-in pyvenv command.
First, create a virtual environment (venv). The directory you install the
venv into is up to you, but for purposes of this document, we’ll install it
into /tmp/mm3
:
$ python3 -m venv /tmp/mm3
Now, in the directory containing Mailman, activate the virtual environment and set it up for development:
$ cd directory/containing/mailman
$ source /tmp/mm3/bin/activate
$ pip install -e .
Sit back and have some Kombucha while you wait for everything to download and install.
Building the documentation
To build the documentation, you need some additional dependencies. The only one you probably need from your OS vendor is graphviz. E.g. On Debian or Ubuntu, you can do:
$ sudo apt install graphviz
All other dependencies should be automatically installed as needed. Build the documentation by running:
$ tox -e docs
Then visit:
build/sphinx/html/index.html
Mailman Shell
This documentation has examples which use the Mailman shell to interact with
Mailman. To start the shell type mailman shell
in your terminal.
There are some testings functions which need to be imported first before you
use them. They can be imported from the modules available in
mailman.testing
. For example, to use dump_list
you first need to
import it from the mailman.testing.documentation
module.
The shell automatically initializes the Mailman system, loads all the available interfaces, and configures the Zope Component Architecture (ZCA) which is used to access all the software components in Mailman. So for example, if you wanted to get access to the list manager component, you could do:
$ mailman shell
Welcome to the GNU Mailman shell
Use commit() to commit changes.
Use abort() to discard changes since the last commit.
Exit with ctrl+D does an implicit commit() but exit() does not.
>>> list_manager = getUtility(IListManager)