src/postorius/doc/development.rst

   1 ===========
   2 Development
   3 ===========
   4
   5 This is a short guide to help you get started with Postorius development.
   6
   7
   8 Development Workflow
   9 ====================
  10
  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
  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 the master branch. There is a contribution guide here_, that mentions the basics
  19 about contributing to any mailman project.
  20
  21 .. _here: http://wiki.list.org/DEV/HowToContributeGit
  22
  23 An ideal workflow would be like this:
  24
  25 1. File a bug to suggest a new feature or report a bug (or just pick one of
  26    the existing bugs).
  27 2. Create a new branch with your code changes.
  28 3. Make a "merge request" to get your code reviewed and merged.
  29
  30
  31 First Contributions / Coverage Reports
  32 ======================================
  33
  34 If you don't know how you can contribute,
  35 writing tests is a good way to get you started.
  36
  37 You can start by exploring the existing `test coverage`_
  38 and finding code that's not covered ie. not tested.
  39
  40 .. _`test coverage`: https://mailman.gitlab.io/postorius/index.html
  41
  42
  43 Installing and running the tests
  44 ================================
  45
  46 After checkout you can run the tests using ``tox``:
  47
  48 ::
  49
  50     $ tox
  51
  52 By default this will test against a couple of different environments.
  53 If you want to only run the tests in a specific environment or a single
  54 module, you can specify this using the ``-e`` option and/or a double
  55 dash:
  56
  57 ::
  58
  59     # List all currently configured envs:
  60     $ tox -l
  61     py36-django22
  62     py36-django31
  63     py36-django32
  64     py36-django-latest
  65     py37-django22
  66     py37-django31
  67     py37-django32
  68     py37-django-latest
  69     py38-django22
  70     py38-django31
  71     py38-django32
  72     py38-django-latest
  73     py39-django22
  74     py39-django31
  75     py39-django32
  76     py39-django-latest
  77     py310-django22
  78     py310-django31
  79     py310-django32
  80     py310-django-latest
  81
  82     # Test Django 3.2 on Python3.7 only:
  83     $ tox -e py37-django32
  84
  85     # Run only tests in ``test_address_activation.py``:
  86     $ tox -e py37-django32-- src/postoriustests/test_address_activation.py
  87
  88     # You get the idea...
  89     $ tox -e py37-django32 -- postorius.tests.test_address_activation
  90
  91
  92 All test modules reside in the ``postorius/src/postorius/tests``
  93 directory. Please have a look at the existing examples.
  94
  95
  96 Calling Mailman's REST API
  97 ==========================
  98
  99 A lot of Postorius' code involves calls to Mailman's REST API (through the
 100 ``mailmanclient`` library). Postorius' test uses `pytest`_ along with
 101 `pytest-django`_ to run tests.
 102
 103 Postorius uses `pytest fixtures`_ to setup Mailman Core's REST API and is
 104 defined at ``postorius.tests.mailman_api_tests.conftest.mailman_rest_layer``. It
 105 is set to ``autouse=True`` so, all the tests inside the module
 106 ``mailman_api_tests`` automatically use it.
 107
 108 ``mailman_rest_layer`` starts up ``incoming`` runner and ``rest`` runner using
 109 ``mailman.testing.helpersTestableMaster``. It also removes all the data after
 110 every ``TestCase`` class.
 111
 112
 113 .. _pytest fixtures: https://docs.pytest.org/en/latest/fixture.html
 114 .. _pytest: https://docs.pytest.org/en/latest/contents.html
 115 .. _pytest-django: https://pytest-django.readthedocs.io/en/latest/
 116
 117
 118 View Authorization
 119 ==================
 120
 121 Three of Django's default User roles are relevant for Postorius:
 122
 123 - Superuser: Can do everything.
 124 - AnonymousUser: Can view list index and info pages.
 125 - Authenticated users: Can view list index and info pages. Can (un)subscribe
 126   from lists.
 127
 128 Apart from these default roles, there are two others relevant in Postorius:
 129
 130 - List owners: Can change list settings, moderate messages and delete their
 131   lists.
 132 - List moderators: Can moderate messages.
 133
 134 There are a number of decorators to protect views from unauthorized users.
 135
 136 - ``@user_passes_test(lambda u: u.is_superuser)`` (redirects to login form)
 137 - ``@login_required`` (redirects to login form)
 138 - ``@list_owner_required`` (returns 403 if logged-in user isn't the
 139   list's owner)
 140 - ``@list_moderator_required`` (returns 403 if logged-in user isn't the
 141   list's moderator)
 142
 143
 144 Accessing the Mailman API
 145 =========================
 146
 147 Postorius uses mailmanclient to connect to Mailman's REST API. In order to
 148 directly use the client, ``cd`` to the ``example_project`` folder and execute
 149 ``python manage.py mmclient``. This will open a python shell (IPython, if
 150 that's available) and provide you with a client object connected to your
 151 local Mailman API server (it uses the credentials from your settings.py).
 152
 153 A quick example:
 154
 155 ::
 156
 157     $ python manage.py mmclient
 158
 159     >>> client
 160     <Client (user:pwd) http://localhost:8001/3.1/>
 161
 162     >>> print(client.system['mailman_version'])
 163     GNU Mailman 3.0.0b2+ (Here Again)
 164
 165     >>> mailman_dev = client.get_list('mailman-developers@python.org')
 166     >>> print(mailman_dev.settings)
 167     {u'description': u'Mailman development',
 168      u'default_nonmember_action': u'hold', ...}
 169
 170 For detailed information how to use mailmanclient, check out its documentation_.
 171
 172 .. _documentation: http://docs.mailman3.org/projects/mailmanclient/en/latest/using.html