diff --git a/src/postorius/doc/development.rst b/src/postorius/doc/development.rst index 63ee036..2fd8e4d 100644 --- a/src/postorius/doc/development.rst +++ b/src/postorius/doc/development.rst @@ -5,45 +5,13 @@ This is a short guide to help you get started with Postorius development. -Directory layout -================ - -Postorius is a Django application, so if you have developed with Django before, -the file structure probably looks familiar. These are the basics: - -:: - - __init__.py - auth/ # Custom authorization code (List owners and - # moderators) - context_processors.py # Some variables available in all templates - doc/ # Sphinx documentation - fieldset_forms.py # A custom form class to build html forms with - # fieldsets - forms.py # All kinds of classes to build and validate forms - management/ # Commands to use with Django's manage.py script - models.py # Code to connect to mailman.client and provide - # a Django-style model API for lists, mm-users and - # domains - static/ # Static files (CSS, JS, images) - templates/ # HTML Templates - tests/ # Postorius test files - urls.py # URL routes - utils.py # Some handy utilities - views/ - views.py # View classes and functions for all views connected - # in urls.py - generic.py # Generic class-based views; Currently holds a - # class for views based on a single mailing list - - Development Workflow ==================== -The source code is hosted on Launchpad_, which also means that we are using +The source code is hosted on Launchpad_, which means that we are using Bazaar for version control. -.. _Launchpad: https://launchpad.net +.. _Launchpad: https://launchpad.net/postorius Changes are usually not made directly in the project's trunk branch, but in feature-related personal branches, which get reviewed and then merged into @@ -61,21 +29,38 @@ .. _tour: https://launchpad.net/+tour/index - -Writing View Code -================= - -When the work on Postorius was started, the standard way to write view code in -Django was to write a single function for each different view. Since then -Django has introduced so-called 'class-based views' which make it much easier -to reuse view functionality. While using simple functions is not discuraged, it -makes sense to check if using a class-based approach could make sense. - -Check Postorius' ``views/views.py`` and ``views/generic.py`` for examples! +Testing +======= -Authentication/Authorization -============================ +After a fresh checkout of Postorius you can run the test from +Postorius' root directory using ``tox``: + +:: + + $ tox + +All test modules reside in the ``postorius/src/postorius/tests`` +directory. + + +Mocking calls to Mailman's REST API +----------------------------------- + +A lot of Postorius' code involves calls to Mailman's REST API (through +the mailman.client library). Running these tests against a real instance +of Mailman would be bad practice and slow, so ``vcrpy`` fixtures are +used instead. See the `vcrpy Documentation`_ for details. + +.. _`vcrpy Documentation`: https://github.com/kevin1024/vcrpy + +If you write new tests, it's advisable to add a separate fixture file +for each test case, so the cached responses don't interfere with other +tests. + + +View Auth +========= Three of Django's default User roles are relvant for Postorius: @@ -94,38 +79,10 @@ - ``@user_passes_test(lambda u: u.is_superuser)`` (redirects to login form) - ``@login_required`` (redirects to login form) -- ``@list_owner_required`` (returns 403) -- ``@list_moderator_required`` (returns 403) -- ``@superuser_or_403`` (returns 403) -- ``@loggedin_or_403`` (returns 403) -- ``@basic_auth_login`` - -Check out ``views/views.py`` or ``views/api.py`` for examples! - -The last one (basic_auth_login) checks the request header for HTTP Basic Auth -credentials and uses those to authenticate against Django's session-based -mechanism. It can be used in cases where a view is accessed from other clients -than the web browser. - -Please make sure to put it outside the other auth decorators. - -Good: - -:: - - @basic_auth_login - @list_owner_required - def my_view_func(request): - ... - -Won't work, because list_owner_required will not recognize the user: - -:: - - @list_owner_required - @basic_auth_login - def my_view_func(request): - ... +- ``@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) Accessing the Mailman API @@ -157,51 +114,3 @@ For detailed information how to use mailman.client, check out its documentation_. .. _documentation: http://bazaar.launchpad.net/~mailman-coders/mailman.client/trunk/view/head:/src/mailmanclient/docs/using.txt - - -Testing -======= - -Currently only some of the Postorius code is covered by a test. We should change that! - -All test modules reside in the ``postorius/src/postorius/tests`` directory -and this is where you should put your own tests, too. To make the django test -runner find your tests, make sure to add them to the folder's ``__init__.py``: - -:: - - from postorius.tests import test_utils - from postorius.tests.test_list_members import ListMembersViewTest - from postorius.tests.test_list_settings import ListSettingsViewTest - from postorius.tests.my_own_tests import MyOwnUnitTest - - __test__ = { - "Test Utils": test_utils, - "List Members": ListMembersViewTest, - "List Settings": ListSettingsViewTest, - "My Own Test": MyOwnUnitTest, - } - - -Running the tests ------------------ - -To run the tests go to your project folder and run ``python manage.py test -postorius`` from there. - - -Testing mailman.client results ------------------------------- - -Most of Postorius' code involves some results from calls to the mailman.client -library. mailman.client is itself covered by tests, so Postorius' own tests -don't need to check if mailman.client returns correct results. Instead we can -just mock them! This has the big advantage that you can run the test suite -without having to worry about the state of the local Mailman database. It also -makes the tests run faster, because we spare ourselves the HTTP calls to the -local Mailman REST API. - -This approach has the obvious downside that the Postorius tests will not -recognize any changes to the Mailman API. So at some point there should be some -separate integration tests to test the whole chain. But let's not worry about -that for now. diff --git a/src/postorius/doc/index.rst b/src/postorius/doc/index.rst index da81de8..829875c 100644 --- a/src/postorius/doc/index.rst +++ b/src/postorius/doc/index.rst @@ -1,7 +1,14 @@ Postorius - The New Mailman Web UI ================================== -Contents: +Copyright (C) 2009-2015 by the Free Software Foundation, Inc. + +This is Postorius, the new official web interface for the GUN Mailman 3 +list management system. + + +Table of Contents +----------------- .. toctree:: :maxdepth: 1 @@ -9,4 +16,3 @@ news.rst setup.rst development.rst - diff --git a/src/postorius/doc/news.rst b/src/postorius/doc/news.rst index 8fd698b..fc904da 100644 --- a/src/postorius/doc/news.rst +++ b/src/postorius/doc/news.rst @@ -34,7 +34,7 @@ * Fix small bug moderator/owner forms on list members page. Contributed by Pranjal Yadav (LP: 1308219). * Fix broken translation string on the login page. Contributed by Pranjal Yadav. * Show held message details in a modal window. Contributed by Abhilash Raj (LP: 1004049). - +* Rework of internal testing 1.0 beta 1 -- "Year of the Parrot" ==================================