6 files changed, 89 insertions, 77 deletions

diff --git a/README.rst b/README.rst
index de4938df8..7ff7535e1 100644
--- a/README.rst
+++ b/README.rst
@@ -35,6 +35,7 @@ Table of Contents
 
     src/mailman/docs/INTRODUCTION
     src/mailman/docs/START
+    src/mailman/docs/RELEASENOTES
     src/mailman/docs/DATABASE
     src/mailman/docs/MTA
     src/mailman/docs/8-miles-high
diff --git a/src/mailman/docs/ACKNOWLEDGMENTS.rst b/src/mailman/docs/ACKNOWLEDGMENTS.rst
index 8ee5b5dd1..4577a26ab 100644
--- a/src/mailman/docs/ACKNOWLEDGMENTS.rst
+++ b/src/mailman/docs/ACKNOWLEDGMENTS.rst
@@ -7,27 +7,37 @@ GNU Mailman Acknowledgments
 Copyright (C) 1998-2015 by the Free Software Foundation, Inc.
 
 
+Governance
+==========
+
+GNU Mailman was invented by John Viega.  Barry Warsaw is the current project
+leader.  Aurélien Bompard leads HyperKitty and bundler development.  Florian
+Fuchs leads Postorious development.  Development of mailman.client is a group
+effort.
+
+All project decisions are made by consensus via the Mailman Cabal, er,
+Steering Committee which can be contacted directly via mailman-cabal@python.org
+
+
 Core Developers
 ===============
 
 The following folks are or have been core developers of Mailman (in reverse
 alphabetical order):
 
+* Abhilash Raj
+* Aurélien Bompard
 * Barry Warsaw, Mailman's yappy guard dog
-* Mark Sapiro, Mailman's compulsive responder
-* Tokio Kikuchi, Mailman's weatherman
-* John Viega, Mailman's inventor
-* Thomas Wouters, Mailman's Dutch treat
+* Florian Fuchs
 * Harald Meland, Norse Mailman
+* John Viega, Mailman's inventor
 * Ken Manheimer, Mailman's savior
+* Mark Sapiro, Mailman's compulsive responder
 * Scott Cotton, Cookie-Monster
-
-
-Steering Committee
-==================
-
-The Mailman Steering Committee can be contacted directly via
-mailman-cabal@python.org
+* Stephen J. Turnbull
+* Terri Oda
+* Thomas Wouters, Mailman's Dutch treat
+* Tokio Kikuchi (RIP), Mailman's weatherman
 
 
 Copyright Assignees
@@ -44,7 +54,6 @@ code, and have assigned copyright for contributions to the FSF:
 * Norbert Bollow
 * Joe Dugan
 * Ethan Mindlace Fremen
-* Florian Fuchs
 * Ben Gertzfield
 * Victoriano Giralt
 * Stephen Goss
@@ -58,7 +67,6 @@ code, and have assigned copyright for contributions to the FSF:
 * Simone Piunno
 * Claudia Schmidt
 * Andreas Schosser
-* Stephen J. Turnbull
 * Richard Wackerbarth
 
 
@@ -101,7 +109,6 @@ left off the list!
 * Stuart Bishop
 * David Blomquist
 * Bojan
-* Aurélien Bompard
 * Søren Bondrup
 * Grant Bowman
 * Alessio Bragadini
diff --git a/src/mailman/docs/DATABASE.rst b/src/mailman/docs/DATABASE.rst
index a64c371f7..a6d1877ed 100644
--- a/src/mailman/docs/DATABASE.rst
+++ b/src/mailman/docs/DATABASE.rst
@@ -71,7 +71,7 @@ Mailman into that, and then run the ``alembic`` command.  For example::
     $ source /tmp/mm3/bin/activate
     $ python setup.py develop
     $ alembic -c src/mailman/config/alembic.cfg revision --autogenerate -m
-	  "<migration_name>"
+      "<migration_name>"
 
 This would create a new migration which would automatically be migrated to the
 database on the next run of Mailman.  Note that the database needs to be in
@@ -85,6 +85,14 @@ People upgrading Mailman from previous versions need not do anything manually,
 as soon as a new migration is added in the sources, it will be automatically
 reflected in the schema on first-run post-update.
 
+**Note:** When auto-generating migrations using Alembic, be sure to check
+the created migration before adding it to the version control.  You will have
+to manually change some of the special data types defined in
+``mailman.database.types``.  For example, ``mailman.database.types.Enum()``
+needs to be changed to ``sa.Integer()``, as the ``Enum`` type stores just the
+integer in the database.  A more complex migration would be needed for
+``UUID`` depending upon the database layer to be used.
+
 
 .. _SQLAlchemy: http://www.sqlalchemy.org/
 .. _SQLite3: http://docs.python.org/library/sqlite3.html
diff --git a/src/mailman/docs/INTRODUCTION.rst b/src/mailman/docs/INTRODUCTION.rst
index 7257044ca..f6f9f2df2 100644
--- a/src/mailman/docs/INTRODUCTION.rst
+++ b/src/mailman/docs/INTRODUCTION.rst
@@ -51,7 +51,7 @@ Mailman was originally developed by John Viega.  Subsequent development
 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
+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.
@@ -79,10 +79,18 @@ lists and archives, etc., are available at:
     http://www.list.org/help.html
 
 
-Requirements
-============
+Bits and pieces
+===============
 
-Mailman 3 requires `Python 3.4`_ or newer.
+Mailman 3 is really a suite of 5 projects:
+
+ * Core - the core message processing and delivery system, exposing a REST API
+   for administrative control.  Requires `Python 3.4`_ or newer.
+ * Postorious - 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.
 
 
 .. _`GNU Mailman`: http://www.list.org
@@ -91,3 +99,5 @@ Mailman 3 requires `Python 3.4`_ or newer.
 .. _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/
diff --git a/src/mailman/docs/RELEASENOTES.rst b/src/mailman/docs/RELEASENOTES.rst
new file mode 100644
index 000000000..226b256a2
--- /dev/null
+++ b/src/mailman/docs/RELEASENOTES.rst
@@ -0,0 +1,23 @@
+===============
+ Release notes
+===============
+
+Mailman 3 is a fully rewritten code base.  The developers believe it has
+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.
+
+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
+mail server and web infrastructure.
+
+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.
+Postorious, Hyperkitty, mailman.client, and the bundler are described and
+developed elsewhere.
diff --git a/src/mailman/docs/START.rst b/src/mailman/docs/START.rst
index 3ca4460b4..688f453d0 100644
--- a/src/mailman/docs/START.rst
+++ b/src/mailman/docs/START.rst
@@ -7,25 +7,6 @@ Getting started with GNU Mailman
 Copyright (C) 2008-2015 by the Free Software Foundation, Inc.
 
 
-Beta Release
-============
-
-This is a beta release.  The developers believe it has sufficient
-functionality to provide full mailing list services, but it is not yet ready
-for production use.
-
-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).  The web interface (known as `Postorius`_) and
-archiver (known as `Hyperkitty`_) are developed separately.
-
-
 Contact Us
 ==========
 
@@ -39,11 +20,12 @@ list, or ask on IRC channel ``#mailman`` on Freenode.
 Requirements
 ============
 
-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.
+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
@@ -53,12 +35,12 @@ Cheeseshop`_.
 Documentation
 =============
 
-The documentation for Mailman 3 is distributed throughout the sources.
-The core documentation (such as this file, ``START.rst``) 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 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
@@ -107,23 +89,13 @@ 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.
+installed, or you can use Python 3's built-in `pyvenv`_ command.
 
-First, create a virtual environment.  By default ``virtualenv`` uses the
-``python`` executable it finds first on your ``$PATH``.  Make sure this is
-Python 3.4 (just start the interactive interpreter and check the version in
-the startup banner).  The directory you install the virtualenv into is up to
-you, but for purposes of this document, we'll install it into ``/tmp/mm3``::
+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``::
 
-    % virtualenv -p python3 --system-site-packages /tmp/mm3
-
-If your default Python is not version 3.4, use the ``--python`` option to
-specify the Python executable.  You can use the command name if this version
-is on your ``PATH``::
-
-    % virtualenv --system-site-packages --python=python3.4 /tmp/mm3
-
-or you may specify the full path to any Python 3.4 executable.
+    % pyvenv /tmp/mm3
 
 Now, activate the virtual environment and set it up for development::
 
@@ -211,13 +183,6 @@ 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,
-based on Florian Fuchs' `Five Minute Guide` from his `blog post`_ on the
-Mailman wiki.  (Check the `blog post`_ for the most recent version!)
-
 
 The Archiver
 ------------
@@ -230,12 +195,9 @@ 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.
+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://launchpad.net/postorius
@@ -249,6 +211,7 @@ A `five minute guide to Hyperkitty`_ is based on Toshio Kuratomi's README.
 .. _`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