Development
This is a short guide to help you get started with Postorius development.
Development Workflow
The source code is hosted on GitLab, which means that we are using Git for version control.
Changes are not made directly in the project’s master branch, but in feature-related personal branches, which get reviewed and then merged into the master branch. There is a contribution guide here, that mentions the basics about contributing to any mailman project.
An ideal workflow would be like this:
File a bug to suggest a new feature or report a bug (or just pick one of the existing bugs).
Create a new branch with your code changes.
Make a “merge request” to get your code reviewed and merged.
First Contributions / Coverage Reports
If you don’t know how you can contribute, writing tests is a good way to get you started.
You can start by exploring the existing test coverage and finding code that’s not covered ie. not tested.
Installing and running the tests
After checkout you can run the tests using tox
:
$ tox
By default this will test against a couple of different environments.
If you want to only run the tests in a specific environment or a single
module, you can specify this using the -e
option and/or a double
dash:
# List all currently configured envs:
$ tox -l
py36-django22
py36-django31
py36-django32
py36-django-latest
py37-django22
py37-django31
py37-django32
py37-django-latest
py38-django22
py38-django31
py38-django32
py38-django-latest
py39-django22
py39-django31
py39-django32
py39-django-latest
py310-django22
py310-django31
py310-django32
py310-django-latest
# Test Django 3.2 on Python3.7 only:
$ tox -e py37-django32
# Run only tests in ``test_address_activation.py``:
$ tox -e py37-django32-- src/postoriustests/test_address_activation.py
# You get the idea...
$ tox -e py37-django32 -- postorius.tests.test_address_activation
All test modules reside in the postorius/src/postorius/tests
directory. Please have a look at the existing examples.
Calling Mailman’s REST API
A lot of Postorius’ code involves calls to Mailman’s REST API (through the
mailmanclient
library). Postorius’ test uses pytest along with
pytest-django to run tests.
Postorius uses pytest fixtures to setup Mailman Core’s REST API and is
defined at postorius.tests.mailman_api_tests.conftest.mailman_rest_layer
. It
is set to autouse=True
so, all the tests inside the module
mailman_api_tests
automatically use it.
mailman_rest_layer
starts up incoming
runner and rest
runner using
mailman.testing.helpersTestableMaster
. It also removes all the data after
every TestCase
class.
Accessing the Mailman API
Postorius uses mailmanclient to connect to Mailman’s REST API. In order to
directly use the client, cd
to the example_project
folder and execute
python manage.py mmclient
. This will open a python shell (IPython, if
that’s available) and provide you with a client object connected to your
local Mailman API server (it uses the credentials from your settings.py).
A quick example:
$ python manage.py mmclient
>>> client
<Client (user:pwd) http://localhost:8001/3.1/>
>>> print(client.system['mailman_version'])
GNU Mailman 3.0.0b2+ (Here Again)
>>> mailman_dev = client.get_list('mailman-developers@python.org')
>>> print(mailman_dev.settings)
{u'description': u'Mailman development',
u'default_nonmember_action': u'hold', ...}
For detailed information how to use mailmanclient, check out its documentation.