development.rst 4.86 KB
Newer Older
1 2 3 4
===========
Development
===========

5 6 7
This is a short guide to help you get started with Postorius development.


8 9 10
Development Workflow
====================

11
The source code is hosted on GitLab_, which means that we are using
12
Git for version control.
13

14
.. _GitLab: https://gitlab.com/mailman/postorius
15

Simon Hanna's avatar
Simon Hanna committed
16
Changes are not made directly in the project's master branch, but in
17
feature-related personal branches, which get reviewed and then merged into
18 19 20 21
the master branch. There is a contribution guide here_, that mentions the basics
about contributing to any mailman project.

.. _here: http://wiki.list.org/DEV/HowToContributeGit
22

Florian Fuchs's avatar
Florian Fuchs committed
23
An ideal workflow would be like this:
24

Simon Hanna's avatar
Simon Hanna committed
25
1. File a bug to suggest a new feature or report a bug (or just pick one of
26 27
   the existing bugs).
2. Create a new branch with your code changes.
Simon Hanna's avatar
Simon Hanna committed
28
3. Make a "merge request" to get your code reviewed and merged.
29 30


Simon Hanna's avatar
Simon Hanna committed
31 32 33 34 35 36 37 38 39 40 41 42
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.

.. _`test coverage`: https://mailman.gitlab.io/postorius/index.html


43 44
Installing and running the tests
================================
45

46
After checkout you can run the tests using ``tox``:
47 48 49 50 51

::

    $ tox

Florian Fuchs's avatar
Florian Fuchs committed
52 53 54 55 56 57 58 59 60
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
61 62 63 64 65 66 67 68 69 70 71 72 73
    py35-django111
    py35-django20
    py35-djangolatest
    py36-django111
    py36-django20
    py36-djangolatest
    py37-django111
    py37-django20
    py37-djangolatest
    pep8

    # Test Django 2.1 on Python3.7 only:
    $ tox -e py37-django21
Florian Fuchs's avatar
Florian Fuchs committed
74

Florian Fuchs's avatar
Florian Fuchs committed
75
    # Run only tests in ``test_address_activation``:
Florian Fuchs's avatar
Florian Fuchs committed
76 77 78
    $ tox -- postorius.tests.test_address_activation

    # You get the idea...
79
    $ tox -e py37-django21 -- postorius.tests.test_address_activation
Florian Fuchs's avatar
Florian Fuchs committed
80 81


82
All test modules reside in the ``postorius/src/postorius/tests``
Simon Hanna's avatar
Simon Hanna committed
83
directory. Please have a look at the existing examples.
84

85

86 87
Calling Mailman's REST API
==========================
88

89 90 91
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.
92

93 94 95 96
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.
Florian Fuchs's avatar
Florian Fuchs committed
97

98 99 100
``mailman_rest_layer`` starts up ``incoming`` runner and ``rest`` runner using
``mailman.testing.helpersTestableMaster``. It also removes all the data after
every ``TestCase`` class.
101 102


103 104 105
.. _pytest fixtures: https://docs.pytest.org/en/latest/fixture.html
.. _pytest: https://docs.pytest.org/en/latest/contents.html
.. _pytest-django: https://pytest-django.readthedocs.io/en/latest/
106 107


108 109
View Authorization
==================
110

111
Three of Django's default User roles are relevant for Postorius:
112 113 114 115

- Superuser: Can do everything.
- AnonymousUser: Can view list index and info pages.
- Authenticated users: Can view list index and info pages. Can (un)subscribe
Simon Hanna's avatar
Simon Hanna committed
116
  from lists.
117

Simon Hanna's avatar
Simon Hanna committed
118
Apart from these default roles, there are two others relevant in Postorius:
119 120

- List owners: Can change list settings, moderate messages and delete their
Simon Hanna's avatar
Simon Hanna committed
121
  lists.
122 123 124 125
- List moderators: Can moderate messages.

There are a number of decorators to protect views from unauthorized users.

126 127
- ``@user_passes_test(lambda u: u.is_superuser)`` (redirects to login form)
- ``@login_required`` (redirects to login form)
128 129 130 131
- ``@list_owner_required`` (returns 403 if logged-in user isn't the
  list's owner)
- ``@list_moderator_required`` (returns 403 if logged-in user isn't the
  list's moderator)
132

133

134 135 136
Accessing the Mailman API
=========================

Simon Hanna's avatar
Simon Hanna committed
137 138
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
139 140 141 142 143 144 145 146 147 148 149
``python manage.py mmclient``. This will open a python shell (IPython, if
that's available) and provide you with a client object connected to to your
local Mailman API server (it uses the credentials from your settings.py).

A quick example:

::

    $ python manage.py mmclient

    >>> client
150
    <Client (user:pwd) http://localhost:8001/3.1/>
151

Simon Hanna's avatar
Simon Hanna committed
152
    >>> print(client.system['mailman_version'])
153 154 155
    GNU Mailman 3.0.0b2+ (Here Again)

    >>> mailman_dev = client.get_list('[email protected]')
Simon Hanna's avatar
Simon Hanna committed
156
    >>> print(mailman_dev.settings)
Simon Hanna's avatar
Simon Hanna committed
157
    {u'description': u'Mailman development',
158 159
     u'default_nonmember_action': u'hold', ...}

Simon Hanna's avatar
Simon Hanna committed
160
For detailed information how to use mailmanclient, check out its documentation_.
161

Abhilash Raj's avatar
Abhilash Raj committed
162
.. _documentation: http://docs.mailman3.org/projects/mailmanclient/en/latest/using.html