diff options
Diffstat (limited to 'src/mailman/docs/START.rst')
| -rw-r--r-- | src/mailman/docs/START.rst | 108 |
1 files changed, 88 insertions, 20 deletions
diff --git a/src/mailman/docs/START.rst b/src/mailman/docs/START.rst index ab2717956..cd7b5247d 100644 --- a/src/mailman/docs/START.rst +++ b/src/mailman/docs/START.rst @@ -2,39 +2,61 @@ Getting started with GNU Mailman ================================ -Copyright (C) 2008-2011 by the Free Software Foundation, Inc. +Copyright (C) 2008-2012 by the Free Software Foundation, Inc. -Alpha Release -============= +Beta Release +============ -The Mailman 3 alpha releases are being provided to give developers and other -interested people an early look at the next major version. As such, some -things may not work yet. Your participation is encouraged. Your feedback and -contributions are welcome. Please submit bug reports on the Mailman bug +This is a beta release. The developers believe it has sufficient +functionality to provide full services to a mailing list, but it is not ready +for production yet. Interfaces and administration may differ substantially +from the alpha series, but changes should be incremental going forward from +beta 1. Changes from the alpha series will be described in notes to the main +text. + +The Mailman 3 beta releases are being provided to give developers and other +interested people an early look at the next major version, and site +administrators a chance to prepare for an eventual upgrade. The core list +management and post distribution functionality is now complete. However, +unlike Mailman 2 whose web interface and archives were tightly integrated with +the core, Mailman 3 exposes a REST administrative interface to the web, +communicates with archivers via decoupled interfaces, and leaves summary, +search, and retrieval of archived messages to a separate application (a simple +implementation is provided). As of beta 1 the web interface and archiver are +still at an early stage of development. As such, some things may not work. + +Contributions are welcome. Please submit bug reports on the Mailman bug tracker at https://bugs.launchpad.net/mailman though you will currently need to have a login on Launchpad to do so. You can also send email to the mailman-developers@python.org mailing list. -Using the Alpha -=============== +Requirements +============ Python 2.6 or 2.7 is required. It can either be the default 'python' on your $PATH or it can be accessible via the ``python2.6`` or ``python2.7`` binary. If your operating system does not include Python, see http://www.python.org downloading and installing it from source. Python 3 is not yet supported. - -Building Mailman 3 -================== +In this documentation, a bare ``python`` refers to the python used to invoke +``bootstrap.py``, which might be ``python2.6`` or ``python2.7``, as well as +the system ``python`` or an absolute path. Mailman 3 is now based on the `zc.buildout`_ infrastructure, which greatly simplifies building and testing Mailman. -You do not need anything other than Python and an internet connection to get -all the other Mailman 3 dependencies. Here are the commands to build -everything:: +During the beta program, you may need some additional dependencies, such as a +C compiler and the Python development headers and libraries. You will need an +internet connection. Also the `web UI`_ and `archive UI`_ are distributed and +installed separately. + + +Building Mailman 3 +================== + +Here are the commands to build everything in core Mailman:: % python bootstrap.py % bin/buildout @@ -50,16 +72,16 @@ You should see no failures. Build the online docs by running:: - % bin/docs + % python setup.py build_sphinx -(You might get warnings which you can safely ignore.) Then visit +(You might get warnings which you can safely ignore.) Then visit:: - parts/docs/mailman/build/mailman/docs/README.html + build/sphinx/html/README.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 works. +how various components of Mailman 3 work. Running Mailman 3 @@ -88,6 +110,7 @@ The first existing file found wins. * ``./mailman.cfg`` * ``~/.mailman.cfg`` * ``/etc/mailman.cfg`` + * ``argv[0]/../../etc/mailman.cfg`` Run the ``bin/mailman info`` command to see which configuration file Mailman will use, and where it will put its database file. The first time you run @@ -102,6 +125,51 @@ The `web ui`_ is being developed as a separate, Django-based project. For now, all configuration happens via the command line and REST API. +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. + +Postorius was prototyped at the `Pycon 2012 sprint`_, so it is "very alpha" as +of Mailman 3 beta 1, and comes in several components. In particular, it +requires a `Django`_ installation, and Bazaar checkouts of the `REST client +module`_ and `Postorius`_ itself. Building it is fairly straightforward, +however, given Florian Fuchs' `Five Minute Guide` from his `blog post`_ on the +Mailman wiki. (Check the `blog post`_ for the most recent version!) + + +The List Archiver +----------------- + +In Mailman 3, the archivers are decoupled from the core engine. It is useful +to provide 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, and +like the web UI it is also in early alpha as of Mailman 3 beta 1. 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. + +A `five minute guide to hyperkitty`_ is based on Toshio Kuratomi's README. + + .. _`zc.buildout`: http://pypi.python.org/pypi/zc.buildout .. _`lazr.config`: http://pypi.python.org/pypi/lazr.config -.. _`web ui`: https://launchpad.net/mailmanweb +.. _`Postorius`: https://launchpad.net/postorius +.. _`archive UI`: https://launchpad.net/hyperkitty +.. _`Django`: http://djangoproject.org/ +.. _`REST client module`: https://launchpad.net/mailman.client +.. _`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/ |