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     py35-django111
  62     py35-django20
  63     py35-djangolatest
  64     py36-django111
  65     py36-django20
  66     py36-djangolatest
  67     py37-django111
  68     py37-django20
  69     py37-djangolatest
  70     pep8
  71
  72     # Test Django 2.1 on Python3.7 only:
  73     $ tox -e py37-django21
  74
  75     # Run only tests in ``test_address_activation``:
  76     $ tox -- postorius.tests.test_address_activation
  77
  78     # You get the idea...
  79     $ tox -e py37-django21 -- postorius.tests.test_address_activation
  80
  81
  82 All test modules reside in the ``postorius/src/postorius/tests``
  83 directory. Please have a look at the existing examples.
  84
  85
  86 Calling Mailman's REST API
  87 ==========================
  88
  89 A lot of Postorius' code involves calls to Mailman's REST API (through the
  90 ``mailmanclient`` library). Postorius' test uses `pytest`_ along with
  91 `pytest-django`_ to run tests.
  92
  93 Postorius uses `pytest fixtures`_ to setup Mailman Core's REST API and is
  94 defined at ``postorius.tests.mailman_api_tests.conftest.mailman_rest_layer``. It
  95 is set to ``autouse=True`` so, all the tests inside the module
  96 ``mailman_api_tests`` automatically use it.
  97
  98 ``mailman_rest_layer`` starts up ``incoming`` runner and ``rest`` runner using
  99 ``mailman.testing.helpersTestableMaster``. It also removes all the data after
 100 every ``TestCase`` class.
 101
 102
 103 .. _pytest fixtures: https://docs.pytest.org/en/latest/fixture.html
 104 .. _pytest: https://docs.pytest.org/en/latest/contents.html
 105 .. _pytest-django: https://pytest-django.readthedocs.io/en/latest/
 106
 107
 108 View Authorization
 109 ==================
 110
 111 Three of Django's default User roles are relevant for Postorius:
 112
 113 - Superuser: Can do everything.
 114 - AnonymousUser: Can view list index and info pages.
 115 - Authenticated users: Can view list index and info pages. Can (un)subscribe
 116   from lists.
 117
 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
 121   lists.
 122 - List moderators: Can moderate messages.
 123
 124 There are a number of decorators to protect views from unauthorized users.
 125
 126 - ``@user_passes_test(lambda u: u.is_superuser)`` (redirects to login form)
 127 - ``@login_required`` (redirects to login form)
 128 - ``@list_owner_required`` (returns 403 if logged-in user isn't the
 129   list's owner)
 130 - ``@list_moderator_required`` (returns 403 if logged-in user isn't the
 131   list's moderator)
 132
 133
 134 Accessing the Mailman API
 135 =========================
 136
 137 Postorius uses mailmanclient to connect to Mailman's REST API. In order to
 138 directly use the client, ``cd`` to the ``example_project`` folder and execute
 139 ``python manage.py mmclient``. This will open a python shell (IPython, if
 140 that's available) and provide you with a client object connected to your
 141 local Mailman API server (it uses the credentials from your settings.py).
 142
 143 A quick example:
 144
 145 ::
 146
 147     $ python manage.py mmclient
 148
 149     >>> client
 150     <Client (user:pwd) http://localhost:8001/3.1/>
 151
 152     >>> print(client.system['mailman_version'])
 153     GNU Mailman 3.0.0b2+ (Here Again)
 154
 155     >>> mailman_dev = client.get_list('mailman-developers@python.org')
 156     >>> print(mailman_dev.settings)
 157     {u'description': u'Mailman development',
 158      u'default_nonmember_action': u'hold', ...}
 159
 160 For detailed information how to use mailmanclient, check out its documentation_.
 161
 162 .. _documentation: http://docs.mailman3.org/projects/mailmanclient/en/latest/using.html