diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/mailman/docs/ARCHITECTURE.rst (renamed from src/mailman/docs/DEVELOP.rst) | 79 | ||||
| -rw-r--r-- | src/mailman/docs/CONTRIBUTE.rst | 287 | ||||
| -rw-r--r-- | src/mailman/docs/INTRODUCTION.rst | 83 | ||||
| -rw-r--r-- | src/mailman/docs/NEWS.rst | 4 | ||||
| -rw-r--r-- | src/mailman/docs/RELEASENOTES.rst | 10 | ||||
| -rw-r--r-- | src/mailman/docs/START.rst | 235 | ||||
| -rw-r--r-- | src/mailman/docs/STYLEGUIDE.rst | 11 |
7 files changed, 394 insertions, 315 deletions
diff --git a/src/mailman/docs/DEVELOP.rst b/src/mailman/docs/ARCHITECTURE.rst index 5b3ee602a..3208ec842 100644 --- a/src/mailman/docs/DEVELOP.rst +++ b/src/mailman/docs/ARCHITECTURE.rst @@ -1,28 +1,27 @@ -================== -Developing Mailman -================== +====================== +Mailman 3 architecture +====================== -The following documentation is generated from the internal developer -documentation. This documentation is also used by the test suite. Another -good source of architectural information is available in the chapter written -by Barry Warsaw for the `Architecture of Open Source Applications`_. +This is a brief overview of the internal architecture of the Mailman 3 core +delivery engine. You should start here if you want to understand how Mailman +works at the 1000 foot level. Another good source of architectural +information is available in the chapter written by Barry Warsaw for the +`Architecture of Open Source Applications`_. -For now, this will have to suffice as an overview of the Mailman system. +User model +========== -Object model -============ - -Every major component of the system is defined in an interface. Look through +Every major component of the system is defined by an interface. Look through ``src/mailman/interfaces`` for an understanding of the system components. Mailman objects which are stored in the database, are defined by *model* classes. Objects such as *mailing lists*, *users*, *members*, and *addresses* are primary objects within the system. -Obviously, the *mailing list* is the central object which holds all the -configuration settings for a particular mailing list. A mailing list is -associated with a *domain*, and all mailing lists are managed by the *mailing -list manager*. +The *mailing list* is the central object which holds all the configuration +settings for a particular mailing list. A mailing list is associated with a +*domain*, and all mailing lists are managed (i.e. created, destroyed, looked +up) via the *mailing list manager*. *Users* represent people, and have a *user id* and a *display name*. Users are linked to *addresses* which represent a single email address. One user @@ -32,12 +31,16 @@ only to *verified* addresses. Users and addresses are managed by the *user manager*. -A *member* is created when a user subscribes to a mailing list, either via -their *preferred address* or explicitly via one of their linked and verified -addresses. Members link an address to a mailing list, and represent regular -members, digest members, list owners, and list moderators. Members can even -represent *non-members* (i.e. people not yet subscribed to the mailing list) -for various moderation purposes. +A *member* is created by linking a *subscriber* to a mailing list. +Subscribers can be: + +* A user, which become members through their *preferred address*. +* An address, which can be linked or unlinked to a user, but must be verified. + +Members also have a *role*, representing regular members, digest members, list +owners, and list moderators. Members can even have the *non-member* role +(i.e. people not yet subscribed to the mailing list) for various moderation +purposes. Process model @@ -52,8 +55,8 @@ sending to the archivers), the *digest* queue (for composing digests), etc. A message in a queue is represented by a single file, a ``.pck`` file. This file contains two objects, serialized as `Python pickles`_. The first object -is the message being processed, already parsed into a more efficient internal -representation. The second object is a metadata dictionary that records +is the message being processed, already parsed into a `more efficient internal +representation`_. The second object is a metadata dictionary that records additional information about the message as it is being processed. ``.pck`` files only exist for messages moving between different system queues. @@ -83,23 +86,23 @@ Rules and chains When a message is first received for posting to a mailing list, Mailman processes the message to determine whether the message is appropriate for the -mailing list. If so, it *approves* the message and it gets posted. Mailman +mailing list. If so, it *accepts* the message and it gets posted. Mailman can also *discard* the message so that no further processing occurs. Mailman -can also *reject* the message, bouncing it back to the original sender, usual -with some indication of why the message was rejected. Mailman can also *hold* -the message for moderator approval. +can also *reject* the message, bouncing it back to the original sender, +usually with some indication of why the message was rejected. Mailman can +also *hold* the message for moderator approval. *Moderation* is the phase of processing that determines which of the above four dispositions will occur for the newly posted message. Moderation does not generally change the message, but it may record information in the metadata dictionary. Moderation is performed by the *in* queue runner. -Each step in the moderation phase is performed by applying a *rule* to the -message and asking whether the rule *hits* or *misses*. Each rule is *linked* -to an action which is taken if the rule hits (i.e. matches). If the rule -misses (i.e. doesn't match), then the next rule is tried. All of the -rule/action links are strung together sequentially into a *chain*, and every -mailing list has a *start chain* where rule processing begins. +Each step in the moderation phase applies a *rule* to the message and asks +whether the rule *hits* or *misses*. Each rule is linked to an *action* which +is taken if the rule hits (i.e. matches). If the rule misses (i.e. doesn't +match), then the next rule is tried. All of the rule/action links are strung +together sequentially into a *chain*, and every mailing list has a *start +chain* where rule processing begins. Actually, every mailing list has *two* start chains, one for regular postings to the mailing list, and another for posting to the owners of the mailing @@ -110,8 +113,9 @@ incoming runner finds the destination mailing list, determines whether the message is for the entire list membership, or the list owners, and retrieves the appropriate start chain. The message is then passed to the chain, where each link in the chain first checks to see if its rule matches, and if so, it -executes the linked action. This action is usually one of the typical -*accept*, *reject*, *discard*, and *hold*, but other actions are possible. +executes the linked action. This action is usually one of *accept*, *reject*, +*discard*, and *hold*, but other actions are possible, such as executing a +function or jumping to another chain. As you might imagine, you can write new rules, compose them into new chains, and configure a mailing list to use your custom chain when processing the @@ -155,5 +159,6 @@ servers. The database layer is an critical piece, and Mailman has an extensive set of command line commands, and email commands. -.. _`Python pickles`: http://docs.python.org/2/library/pickle.html .. _`Architecture of Open Source Applications`: http://www.aosabook.org/en/mailman.html +.. _`Python pickles`: http://docs.python.org/2/library/pickle.html +.. _`more efficient internal representation`: https://docs.python.org/3/library/email.html diff --git a/src/mailman/docs/CONTRIBUTE.rst b/src/mailman/docs/CONTRIBUTE.rst new file mode 100644 index 000000000..12dc59b3c --- /dev/null +++ b/src/mailman/docs/CONTRIBUTE.rst @@ -0,0 +1,287 @@ +.. _start-here: + +========================= +Contributing to Mailman 3 +========================= + +Copyright (C) 2008-2016 by the Free Software Foundation, Inc. + + +Contact Us +========== + +Contributions of code, problem reports, and feature requests are welcome. +Please submit bug reports on the Mailman bug tracker at +https://gitlab.com/mailman/mailman/issues (you need to have a login on GitLab +to do so). You can also send email to the mailman-developers@python.org +mailing list, or ask on IRC channel ``#mailman`` on Freenode. + + +Requirements +============ + +For the Core, Python 3.4 or newer is required. It can either be the default +'python3' on your ``$PATH`` or it can be accessible via the ``python3.4`` or +``python3.5`` binary. If your operating system does not include Python 3, see +http://www.python.org for information about downloading installers (where +available) and installing it from source (when necessary or preferred). +Python 2 is not supported by the Core. + +You may need some additional dependencies, which are either available from +your OS vendor, or can be downloaded automatically from the `Python +Cheeseshop`_. + + +Documentation +============= + +The documentation for Mailman 3 is distributed throughout the sources. The +core documentation (such as this file) is found in the ``src/mailman/docs`` +directory, but much of the documentation is in module-specific places. Online +versions of the `Mailman 3 Core documentation`_ is available online. + + +How to contribute +================= + +We accept `merge requests`_ and `bug reports`_ on GitLab. We prefer if every +merge request is linked to a bug report, because we can more easily manage the +priority of bug reports. For more substantial contributions, we may ask you +to sign a `copyright assignment`_ to the Free Software Foundation, the owner +of the GNU Mailman copyright. If you'd like to jump start your copyright +assignment, please contact the GNU Mailman `steering committee`_. + + +Testing Mailman 3 +================= + +To run the Mailman test suite, just use the `tox`_ command:: + + $ tox + +`tox` creates a virtual environment (virtualenv) for you, installs all the +dependencies into that virtualenv, and runs the test suite from that +virtualenv. By default it does not use the `--system-site-packages` so it +downloads everything from the Cheeseshop. + +A bare ``tox`` command will try to run several test suites, which might take a +long time, and/or require versions of Python or other components you might not +have installed. You can run ``tox -l`` to list the test suite *environments* +available. Very often, when you want to run the full test suite in the +quickest manner with components that should be available everywhere, run one +of these command, depending on which version of Python 3 you have:: + + $ tox -e py35 + $ tox -e py34 + +You can run individual tests in any given environment by providing additional +positional arguments. For example, to run only the tests that match a +specific pattern:: + + $ tox -e py35 -- -P user + +You can see all the other arguments supported by the test suite by running:: + + $ tox -e py35 -- --help + +You also have access to the virtual environments created by tox, and you can +use this run the virtual environment's Python executable, or run the +``mailman`` command locally, e.g.:: + + $ .tox/py35/bin/python + $ .tox/py35/bin/mailman --help + +If you want to set up the virtual environment without running the full test +suite, you can do this:: + + $ tox -e py35 --notest -r + + +Testing with PostgreSQL +======================== + +By default, the test suite runs with the built-in SQLite database engine. If +you want to run the full test suite against the PostgreSQL database, set the +database up as described in :doc:`DATABASE`, then create a `postgres.cfg` file +any where you want. This `postgres.cfg` file will contain the ``[database]`` +section for PostgreSQL, e.g.:: + + [database] + class: mailman.database.postgresql.PostgreSQLDatabase + url: postgres://myuser:mypassword@mypghost/mailman + +Then run the test suite like so:: + + $ MAILMAN_EXTRA_TESTING_CFG=/path/to/postgres.cfg tox -e py35-pg + +You can combine these ways to invoke Mailman, so if you want to run an +individual test against PostgreSQL, you could do:: + + $ MAILMAN_EXTRA_TESTING_CFG=/path/to/postgres.cfg tox -e py35-pg -- -P user + +Note that the path specified in `MAILMAN_EXTRA_TESTING_CFG` must be an +absolute path or some tests will fail. + + +Building for development +======================== + +To build Mailman for development purposes, you can create a virtual +environment outside of tox. You need to have the `virtualenv`_ program +installed, or you can use Python 3's built-in `pyvenv`_ command. + +First, create a virtual environment (venv). The directory you install the +venv into is up to you, but for purposes of this document, we'll install it +into ``/tmp/mm3``:: + + $ python3 -m venv /tmp/mm3 + +Now, activate the virtual environment and set it up for development:: + + % source /tmp/mm3/bin/activate + % python setup.py develop + +Sit back and have some Kombucha while you wait for everything to download and +install. + + +Building the documentation +========================== + +Build the online docs by running:: + + $ tox -e docs + +Then visit:: + + build/sphinx/html/index.html + + +Running Mailman 3 +================= + +What, you actually want to *run* Mailman 3? Oh well, if you insist. + +You will need to set up a configuration file to override the defaults and set +things up for your environment. Mailman is configured using an "ini"-style +configuration system. + +``src/mailman/config/schema.cfg`` defines the ini-file schema and contains +documentation for every section and configuration variable. Sections that end +in ``.template`` or ``.master`` are templates that must be overridden in +actual configuration files. There is a default configuration file that +defines these basic overrides in ``src/mailman/config/mailman.cfg``. Your own +configuration file will override those. + +By default, all runtime files are put under a ``var`` directory in the current +working directory. **Be careful though because running the test suite will +blow this directory away.** + +Mailman searches for its configuration file using the following search path. +The first existing file found wins. + +* ``-C config`` command line option +* ``$MAILMAN_CONFIG_FILE`` environment variable +* ``./mailman.cfg`` +* ``~/.mailman.cfg`` +* ``/etc/mailman.cfg`` +* ``argv[0]/../../etc/mailman.cfg`` + +Run the ``mailman info`` command to see which configuration file Mailman will +use, and where it will put its database file. The first time you run this, +Mailman will also create any necessary run-time directories and log files. + +Try ``mailman --help`` for more details. You can use the commands +``mailman start`` to start the runner subprocess daemons, and of course +``mailman stop`` to stop them. + +Postorius, a web UI for administration and subscriber settings, is being +developed as a separate, Django-based project. For now, the most flexible +means of configuration is via the command line and REST API. + +Note that you can also "run" Mailman from one of the virtual environments +created by tox, e.g.:: + + $ .tox/py35/bin/mailman info + + +Mailman Shell +============= + +This documentation has examples which use the Mailman shell to interact with +Mailman. To start the shell type ``mailman shell`` in your terminal. + +There are some testings functions which need to be imported first before you +use them. They can be imported from the modules available in +``mailman.testing``. For example, to use ``dump_list`` you first need to +import it from the ``mailman.testing.documentation`` module. + +The shell automatically initializes the Mailman system, loads all the +available interfaces, and configures the `Zope Component Architecture`_ (ZCA) +which is used to access all the software components in Mailman. So for +example, if you wanted to get access to the list manager component, you could +do:: + + $ mailman shell + Welcome to the GNU Mailman shell + + >>> list_manager = getUtility(IListManager) + + +Related projects +================ + +What you are looking at right now is the Mailman Core. It's "just" the +message delivery engine, but it's designed to work with a web user interface +for list members and administrators, and an archiver. The GNU Mailman project +also develops a web ui and archiver, but these are available in separate git +repositories. + + +Mailman Web UI +-------------- + +The Mailman 3 web UI, called *Postorius*, interfaces to core Mailman engine +via the REST client API. This architecture makes it possible for users with +other needs to adapt the web UI, or even replace it entirely, with a +reasonable amount of effort. However, as a core feature of Mailman, the web +UI emphasizes usability over modularity at first, so most users should use the +web UI described here. Postorius is a Django_ application. + + +The Archiver +~~~~~~~~~~~~ + +In Mailman 3, the archivers are decoupled from the Core. Instead, Mailman 3 +provides a simple, standard interface for third-party archiving tools and +services. For this reason, Mailman 3 defines a formal interface to insert +messages into any of a number of configured archivers, using whatever protocol +is appropriate for that archiver. Summary, search, and retrieval of archived +posts are handled by a separate application. + +A new archive UI called `HyperKitty`_, based on the `notmuch mail indexer`_ +was prototyped at the PyCon 2012 sprint by Toshio Kuratomi. The HyperKitty +archiver is very loosely coupled to Mailman 3 core. In fact, any email +application that speaks LMTP or SMTP will be able to use HyperKitty. +HyperKitty is also a Django application. + + +.. _`Postorius`: https://gitlab.com/mailman/postorius +.. _`HyperKitty`: https://gitlab.com/mailman/hyperkitty +.. _`Django`: http://djangoproject.org/ +.. _`REST client module`: https://gitlab.com/mailman/mailmanclient +.. _`Five Minute Guide the Web UI`: WebUIin5.html +.. _`blog post`: http://wiki.list.org/display/DEV/A+5+minute+guide+to+get+the+Mailman+web+UI+running +.. _`notmuch mail indexer`: http://notmuchmail.org +.. _`five minute guide to Hyperkitty`: ArchiveUIin5.html +.. _`Pycon 2012 sprint`: https://us.pycon.org/2012/community/sprints/projects/ +.. _`Python Cheeseshop`: http://pypi.python.org/pypi +.. _`virtualenv`: http://www.virtualenv.org/en/latest/ +.. _`pyvenv`: https://docs.python.org/3/library/venv.html +.. _`Mailman 3 Core documentation`: https://mailman.readthedocs.io +.. _tox: https://testrun.org/tox/latest/ +.. _`merge requests`: https://gitlab.com/mailman/mailman/merge_requests +.. _`bug reports`: https://gitlab.com/mailman/mailman/issues +.. _`copyright assignment`: https://www.fsf.org/licensing/assigning.html/?searchterm=copyright%20assignment +.. _`steering committee`: mailto:mailman-cabal@python.org +.. _`Zope Component Architecture`: https://pypi.python.org/pypi/zope.component diff --git a/src/mailman/docs/INTRODUCTION.rst b/src/mailman/docs/INTRODUCTION.rst index d7dd533e4..2ed7f737e 100644 --- a/src/mailman/docs/INTRODUCTION.rst +++ b/src/mailman/docs/INTRODUCTION.rst @@ -12,7 +12,22 @@ includes GNU/Linux and most other Unix-like operating systems (e.g. Solaris, mail clients on any platform should be able to interact with Mailman just fine. -Learn more about GNU Mailman in the `Getting Started`_ documentation. +GNU Mailman 3 consists of a `suite of programs`_ that work together: + +* Mailman Core; the core delivery engine. This is where you are right now. +* Postorius; the web user interface for list members and administrators. +* HyperKitty; the web-based archiver +* Mailman client; the official Python bindings for talking to the Core's REST + administrative API. +* Mailman bundler; a convenient way to deploy Mailman 3. + +Only the Core is required. You could easily write your own web user interface +or archiver that speaks to the Core over its REST API. The REST API is a pure +HTTP-based API so you don't *have* to use Python, or even our official +bindings. And you can deploy whatever components you want using whatever +mechanisms you want. + +But we really like Postorius and HyperKitty and hope you will too! Copyright @@ -46,58 +61,64 @@ name is `GNU Mailman` but is often referred colloquially as `Mailman`. History ======= -Mailman was originally developed by John Viega. Subsequent development -(through version 1.0b3) was by Ken Manheimer. Further work towards the 1.0 -final release was a group effort, with the core contributors being: Barry -Warsaw, Ken Manheimer, Scott Cotton, Harald Meland, and John Viega. Version -1.0 and beyond have been primarily maintained by Barry Warsaw with -contributions from many; see the `ACKNOWLEDGMENTS`_ file for details. Jeremy -Hylton helped considerably with the Pipermail code in Mailman 2.0. Mailman -2.1 is primarily maintained by Mark Sapiro, with previous help by Tokio -Kikuchi. Barry Warsaw is the lead developer on Mailman 3. +Mailman was originally developed by John Viega in the mid-1990s. Subsequent +development (through version 1.0b3) was by Ken Manheimer. Further work +towards the 1.0 final release was a group effort, with the core contributors +being: Barry Warsaw, Ken Manheimer, Scott Cotton, Harald Meland, and John +Viega. Version 1.0 and beyond have been primarily maintained by Barry Warsaw +with contributions from many; see the `ACKNOWLEDGMENTS`_ file for details. +Jeremy Hylton helped considerably with the Pipermail code in Mailman 2.0. +Mailman 2.1 is primarily maintained by Mark Sapiro, with previous help by +Tokio Kikuchi. Barry Warsaw is the lead developer on Mailman 3. Aurélien +Bompard and Florian Fuchs lead development of Postorius and HyperKitty. +Abhilash Raj is a valued contributor to all bits and maintains the CI +infrastructure. -Help -==== +Project details +=============== The Mailman home page is: - http://www.list.org - -with mirrors at: - - * http://www.gnu.org/software/mailman - * http://mailman.sf.net +* http://www.list.org The community driven wiki (including the FAQ_) is at: - http://wiki.list.org +* http://wiki.list.org Other help resources, such as on-line documentation, links to the mailing lists and archives, etc., are available at: - http://www.list.org/help.html +* http://www.list.org/help.html +Mailman 3 is maintained on GitLab: -Bits and pieces -=============== +* https://gitlab.com/groups/mailman + +You can report issues in the Core at: + +* https://gitlab.com/mailman/mailman/issues + +(GNU Mailman 2.1 is still maintained on Launchpad_.) + +There are two mailing lists you can use to contact the Mailman 3 developers. +The general development mailing list: + +* https://mail.python.org/mailman/listinfo/mailman-developers + +and the Mailman 3 users list: -Mailman 3 is really a suite of 5 projects: +* https://lists.mailman3.org/mailman3/lists/mailman-users.mailman3.org/ - * Core - the core message processing and delivery system, exposing a REST API - for administrative control. Requires `Python 3.4`_ or newer. - * Postorius - the new web user interfaces built on `Django`_. - * HyperKitty - the new archiver, also built on `Django`_. - * mailman.client - a Python binding to the core's REST API. Compatible with - both Python 2 and Python 3. - * Bundler - a convenient installer. +For now, please leave the older mailman-users mailing list for Mailman 2. .. _`GNU Mailman`: http://www.list.org .. _`GNU General Public License`: http://www.gnu.org/licenses/gpl.txt -.. _`Getting Started`: START.html .. _Python: http://www.python.org .. _FAQ: http://wiki.list.org/display/DOC/Frequently+Asked+Questions .. _`Python 3.4`: https://www.python.org/downloads/release/python-342/ .. _`ACKNOWLEDGMENTS`: ACKNOWLEDGMENTS.html .. _`Django`: https://www.djangoproject.com/ +.. _`suite of programs`: http://docs.mailman3.org/en/latest/ +.. _Launchpad: https://launchpad.net/mailman diff --git a/src/mailman/docs/NEWS.rst b/src/mailman/docs/NEWS.rst index e2e3f17e1..73586269b 100644 --- a/src/mailman/docs/NEWS.rst +++ b/src/mailman/docs/NEWS.rst @@ -154,8 +154,8 @@ REST Bompard. * The REST API incorrectly parsed `is_server_owner` values when given explicitly in the POST that creates a user. (Closes #136) - * A new top-level resource `<api>/owners` can be used to get the list of - server owners as `IUser`s. (Closes #135) + * A new top-level resource ``<api>/owners`` can be used to get the list of + server owners as ``IUser`` s. (Closes #135) * By POSTing to a user resource with an existing unlinked address, you can link the address to the user. Given by Abhilash Raj. * Fix pagination values `start` and `total_size` in the REST API. Given by diff --git a/src/mailman/docs/RELEASENOTES.rst b/src/mailman/docs/RELEASENOTES.rst index 9ccf379e6..00d29bb7e 100644 --- a/src/mailman/docs/RELEASENOTES.rst +++ b/src/mailman/docs/RELEASENOTES.rst @@ -7,8 +7,8 @@ sufficient functionality to provide full mailing list services. It should be ready for production use by experienced system developers, but it may not be easy to install or run by novices. -We expect it to be possible to migrate Mailman 2.1 mailing lists to Mailman 3, -but sufficient caution, backups, and testing should be performed. +It should also be possible to migrate Mailman 2.1 mailing lists to Mailman 3. +Caution, backups, and testing is recommended. We expect it to be possible to run Mailman 3 and Mailman 2.1 together on the same systems, but you may need to be quite experienced with configuring your @@ -18,9 +18,9 @@ Mailman 3 may have bugs. Mailman 3 is not yet feature complete with Mailman 2.1. -The documentation here describes the Mailman Core in great detail. -Postorius, Hyperkitty, mailman.client, and the bundler are described and -developed elsewhere. +The documentation here describes the Mailman Core in great detail. Postorius, +Hyperkitty, mailman.client, and the bundler are described and developed +elsewhere. More release notes are maintained on the `Mailman wiki`_. diff --git a/src/mailman/docs/START.rst b/src/mailman/docs/START.rst deleted file mode 100644 index 94db25146..000000000 --- a/src/mailman/docs/START.rst +++ /dev/null @@ -1,235 +0,0 @@ -.. _start-here: - -================================ -Getting started with GNU Mailman -================================ - -Copyright (C) 2008-2016 by the Free Software Foundation, Inc. - - -Contact Us -========== - -Contributions of code, problem reports, and feature requests are welcome. -Please submit bug reports on the Mailman bug tracker at -https://gitlab.com/mailman/mailman/issues (you need to have a login on Gitlab -to do so). You can also send email to the mailman-developers@python.org -mailing list, or ask on IRC channel ``#mailman`` on Freenode. - - -Requirements -============ - -For the Core, Python 3.4 or newer is required. It can either be the default -'python3' on your ``$PATH`` or it can be accessible via the ``python3.4`` -binary. If your operating system does not include Python, see -http://www.python.org for information about downloading installers (where -available) and installing it from source (when necessary or preferred). -Python 2 is not supported. - -You may need some additional dependencies, which are either available from -your OS vendor, or can be downloaded automatically from the `Python -Cheeseshop`_. - - -Documentation -============= - -The documentation for Mailman 3 is distributed throughout the sources. The -core documentation (such as this file) is found in the ``src/mailman/docs`` -directory, but much of the documentation is in module-specific places. A -prebuilt HTML version of `Mailman 3 documentation`_ is available at -pythonhosted.org, as is `Postorius documentation`_. `HyperKitty -documentation`_ is available at ReadTheDocs. - -The `Development Setup Guide`_ is a recent step-by-step explanation of -how to set up a complete Mailman 3 system including the Mailman 3 core -and basic client API, Postorius, and HyperKitty. - -Testing Mailman 3 -================= - -To run the Mailman test suite, just use the `tox`_ command:: - - $ tox - -`tox` creates a virtual environment (virtualenv) for you, installs all the -dependencies into that virtualenv, and runs the test suite from that -virtualenv. By default it does not use the `--system-site-packages` so it -downloads everything from the Cheeseshop. - -You do have access to the virtualenv, and you can use this to run individual -tests, e.g.:: - - $ .tox/py34/bin/python -m nose2 -vv -P user - -Use `.tox/py34/bin/python -m nose2 --help` for more options. - -If you want to run the full test suite against the PostgreSQL database, set -the database up as described in :doc:`DATABASE`, then create a `postgres.cfg` -file any where you want. This `postgres.cfg` file will contain the -``[database]`` section for PostgreSQL, e.g.:: - - [database] - class: mailman.database.postgresql.PostgreSQLDatabase - url: postgres://myuser:mypassword@mypghost/mailman - -Then run the test suite like so:: - - $ MAILMAN_EXTRA_TESTING_CFG=/path/to/postgres.cfg tox -e pg - -If you want to run an individual test against PostgreSQL, you would do it like -so:: - - $ MAILMAN_EXTRA_TESTING_CFG=/path/to/postgres.cfg .tox/pg/bin/python -m nose2 -vv -P user - -Note that the path specified in `MAILMAN_EXTRA_TESTING_CFG` must be an -absolute path or some tests will fail. - - -Building for development ------------------------- - -To build Mailman for development purposes, you can create a virtual -environment outside of tox. You need to have the `virtualenv`_ program -installed, or you can use Python 3's built-in `pyvenv`_ command. - -First, create a virtual environment (venv). The directory you install the -venv into is up to you, but for purposes of this document, we'll install it -into ``/tmp/mm3``:: - - % pyvenv /tmp/mm3 - -Now, activate the virtual environment and set it up for development:: - - % source /tmp/mm3/bin/activate - % python setup.py develop - -Sit back and have some Kombucha while you wait for everything to download and -install. - -Build the online docs by running:: - - % python setup.py build_sphinx - -If ``setup.py`` fails to recognize the ``build_sphinx`` command, then -just install Sphinx in your virtualenv:: - - % pip install sphinx - -This will automatically add the ``build_sphinx`` command to -``setup.py``, so just re-run the command. - -Then visit:: - - build/sphinx/html/index.html - -in your browser to start reading the documentation. Or you can just read the -doctests by looking in all the 'doc' directories under the 'mailman' package. -Doctests are documentation first, so they should give you a pretty good idea -how various components of Mailman 3 work. - -Once everything is downloaded and installed, you can initialize Mailman and -get a display of the basic configuration settings by running:: - - $ mailman info -v - - -Running Mailman 3 -================= - -What, you actually want to *run* Mailman 3? Oh well, if you insist. You will -need to set up a configuration file to override the defaults and set things up -for your environment. Mailman is configured using an "ini"-style -configuration system. - -``src/mailman/config/schema.cfg`` defines the ini-file schema and contains -documentation for every section and configuration variable. Sections that end -in `.template` or `.master` are templates that must be overridden in actual -configuration files. There is a default configuration file that defines these -basic overrides in ``src/mailman/config/mailman.cfg``. Your own configuration -file will override those. - -By default, all runtime files are put under a `var` directory in the current -working directory. - -Mailman searches for its configuration file using the following search path. -The first existing file found wins. - - * ``-C config`` command line option - * ``$MAILMAN_CONFIG_FILE`` environment variable - * ``./mailman.cfg`` - * ``~/.mailman.cfg`` - * ``/etc/mailman.cfg`` - * ``argv[0]/../../etc/mailman.cfg`` - -Run the ``mailman info`` command to see which configuration file Mailman will -use, and where it will put its database file. The first time you run this, -Mailman will also create any necessary run-time directories and log files. - -Try ``mailman --help`` for more details. You can use the commands -``mailman start`` to start the runner subprocess daemons, and of course -``mailman stop`` to stop them. - -Postorius, a web UI for administration and subscriber settings, is being -developed as a separate, Django-based project. For now, the most flexible -means of configuration is via the command line and REST API. - - -Mailman Shell -------------- - -The `Mailman 3 documentation`_ has examples which use the Mailman shell to -interact with Mailman. To start the shell type ``mailman shell`` in your -terminal. - -There are some testings functions which need to be imported first before you -use them. They can be imported from the modules available in -``mailman.testing``. For example, to use ``dump_list`` you first need to -import it from the ``mailman.testing.documentation`` module. - - -Mailman Web UI --------------- - -The Mailman 3 web UI, called *Postorius*, interfaces to core Mailman engine -via the REST client API. It is expected that this architecture will make it -possible for users with other needs to adapt the web UI, or even replace it -entirely, with a reasonable amount of effort. However, as a core feature of -Mailman, the web UI will emphasize usability over modularity at first, so most -users should use the web UI described here. - - -The Archiver ------------- - -In Mailman 3, the archivers are decoupled from the core engine. Instead, -Mailman 3 provides a simple, standard interface for third-party archiving tools -and services. For this reason, Mailman 3 defines a formal interface to insert -messages into any of a number of configured archivers, using whatever protocol -is appropriate for that archiver. Summary, search, and retrieval of archived -posts are handled by a separate application. - -A new archive UI called `Hyperkitty`_, based on the `notmuch mail indexer`_ -and `Django`_, was prototyped at the PyCon 2012 sprint by Toshio Kuratomi. -The Hyperkitty archiver is very loosely coupled to Mailman 3 core. In fact, -any email application that speaks LMTP or SMTP will be able to use Hyperkitty. - - -.. _`Postorius`: https://gitlab.com/mailman/postorius -.. _`Hyperkitty`: https://gitlab.com/mailman/hyperkitty -.. _`Django`: http://djangoproject.org/ -.. _`REST client module`: https://gitlab.com/mailman/mailmanclient -.. _`Five Minute Guide the Web UI`: WebUIin5.html -.. _`blog post`: http://wiki.list.org/display/DEV/A+5+minute+guide+to+get+the+Mailman+web+UI+running -.. _`notmuch mail indexer`: http://notmuchmail.org -.. _`five minute guide to Hyperkitty`: ArchiveUIin5.html -.. _`Pycon 2012 sprint`: https://us.pycon.org/2012/community/sprints/projects/ -.. _`Python Cheeseshop`: http://pypi.python.org/pypi -.. _`virtualenv`: http://www.virtualenv.org/en/latest/ -.. _`pyvenv`: https://docs.python.org/3/library/venv.html -.. _`Mailman 3 documentation`: http://www.pythonhosted.org/mailman/ -.. _`Postorius documentation`: http://www.pythonhosted.org/postorius/ -.. _`HyperKitty documentation`: https://hyperkitty.readthedocs.org/en/latest/development.html -.. _`Development Setup Guide`: https://fedorahosted.org/hyperkitty/wiki/DevelopmentSetupGuide -.. _tox: https://testrun.org/tox/latest/ diff --git a/src/mailman/docs/STYLEGUIDE.rst b/src/mailman/docs/STYLEGUIDE.rst index 31ece2296..1ac3c87e3 100644 --- a/src/mailman/docs/STYLEGUIDE.rst +++ b/src/mailman/docs/STYLEGUIDE.rst @@ -13,13 +13,14 @@ Mailman. `PEP 8`_ is the basis for this style guide so its recommendations should be followed except for the differences outlined here. This document assumes the use of Python 3. +Much of the style guide is enforced by the command ``tox -e qa``. + * When creating new modules, start with the `GNU Mailman Python template`_ as an example. -* Names which should be imported by ``from-import`` should be added to - ``__all__`` but use the ``@public`` decorator from the top-level ``mailman`` - package to do this for all classes and functions. Constants and other - simple name bindings must be added to ``__all__`` explicitly. +* Public module-global names should be exported in the ``__all__`` but use the + ``@public`` decorator from the top-level ``mailman`` package to do this for + all classes and functions. * Imports are always put at the top of the file, just after any module comments and docstrings, and before module globals and constants. @@ -57,7 +58,7 @@ assumes the use of Python 3. or obvious comments in just to avoid vertical whitespace though. * Unless internal quote characters would mess things up, the general rule is - that single quotes should be used for short strings, double quotes for + that single quotes should be used for short strings and double quotes for triple-quoted multi-line strings and docstrings. E.g.:: foo = 'a foo thing' |