4 files changed, 64 insertions, 38 deletions

diff --git a/src/mailman/database/alembic/env.py b/src/mailman/database/alembic/env.py
index 5fb9ac138..a039a20e6 100644
--- a/src/mailman/database/alembic/env.py
+++ b/src/mailman/database/alembic/env.py
@@ -25,11 +25,18 @@ __all__ = [
 
 from alembic import context
 from contextlib import closing
+from mailman.core.initialize import initialize_1
 from mailman.config import config
 from mailman.database.model import Model
 from mailman.utilities.string import expand
 from sqlalchemy import create_engine
 
+try:
+    url = expand(config.database.url, config.paths)
+except AttributeError:
+    # Initialize config object for external alembic calls
+    initialize_1()
+    url = expand(config.database.url, config.paths)
 
 
 def run_migrations_offline():
@@ -42,7 +49,6 @@ def run_migrations_offline():
     Calls to context.execute() here emit the given string to the script
     output.
     """
-    url = expand(config.database.url, config.paths)
     context.configure(url=url, target_metadata=Model.metadata)
     with context.begin_transaction():
         context.run_migrations()
@@ -54,7 +60,6 @@ def run_migrations_online():
     In this scenario we need to create an Engine and associate a
     connection with the context.
     """
-    url = expand(config.database.url, config.paths)
     engine = create_engine(url)
 
     connection = engine.connect()
diff --git a/src/mailman/docs/DATABASE.rst b/src/mailman/docs/DATABASE.rst
index 688a989e6..5f46bbefb 100644
--- a/src/mailman/docs/DATABASE.rst
+++ b/src/mailman/docs/DATABASE.rst
@@ -59,8 +59,35 @@ it::
 My thanks to Stephen A. Goss for his contribution of PostgreSQL support.
 
 
+Database Migrations
+===================
+
+Mailman uses `Alembic`_ to manage database migrations.  Let's say you change
+something in the models, what steps are needed to reflect that change in the
+database schema?  You need to create and enter a virtual environment, install
+Mailman into that, and then run the ``alembic`` command.  For example::
+
+    $ virtualenv -p python3 /tmp/mm3
+    $ source /tmp/mm3/bin/activate
+    $ python setup.py develop
+    $ alembic -c src/mailman/config/alembic.cfg revision --autogenerate
+
+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
+the older state so that Alembic can track the changes in the schema and
+autogenerate a migration.  If you don't have the database in the older state
+you can remove the `--autogenerate` flag in the above command.  It would then
+create a new empty revision which you can edit manually to reflect your
+changes in the database schema.
+
+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.
+
+
 .. _SQLAlchemy: http://www.sqlalchemy.org/
 .. _SQLite3: http://docs.python.org/library/sqlite3.html
 .. _PostgreSQL: http://www.postgresql.org/
 .. _MySQL: http://dev.mysql.com/
 .. _`Ubuntu article`: https://help.ubuntu.com/community/PostgreSQL
+.. _`Alembic`: https://alembic.readthedocs.org/en/latest/
diff --git a/src/mailman/docs/NEWS.rst b/src/mailman/docs/NEWS.rst
index 62162280f..ba8fa61bd 100644
--- a/src/mailman/docs/NEWS.rst
+++ b/src/mailman/docs/NEWS.rst
@@ -28,6 +28,11 @@ Configuration
    file's ``[paths.*]`` sections.  A new ``[paths.here]`` section is added,
    which puts the ``var_dir`` in ``$cwd``.  It is made the default layout.
 
+Documentation
+-------------
+ * Improve the documentation describing how to run Alembic to add new schema
+   migrations.  Given by Abhilash Raj.
+
 REST
 ----
  * You can now view the contents of, inject messages into, and delete messages
diff --git a/src/mailman/docs/WebUIin5.rst b/src/mailman/docs/WebUIin5.rst
index 6419e4752..135f50484 100644
--- a/src/mailman/docs/WebUIin5.rst
+++ b/src/mailman/docs/WebUIin5.rst
@@ -7,11 +7,13 @@ Mailman 3's web UI, called Postorius.  If all goes as planned, you should be
 done within 5 minutes.  This has been tested on Ubuntu 11.04.
 
 In order to download the components necessary you need to have the `Bazaar`_
-version control system installed on your system.  Mailman requires Python 2.7,
+version control system installed on your system.  Mailman requires Python 3.4,
 while mailman.client needs at least Python version 2.6.
 
 It's probably a good idea to set up a virtual Python environment using
-`virtualenv`_.  `Here is a brief HOWTO`_.
+`virtualenv`_.  `Here is a brief HOWTO`_.  You would need two separate virtual
+environment one using Python version 2.6 or 2.7 (for Postorius and
+mailman.client) and other using Python version 3.4 (for Mailman core).
 
 .. _`virtualenv`: http://pypi.python.org/pypi/virtualenv
 .. _`Here is a brief HOWTO`: ./ArchiveUIin5.html#get-it-running-under-virtualenv
@@ -24,19 +26,17 @@ GNU Mailman 3
 First download the latest revision of Mailman 3 from Launchpad.
 ::
 
-  $ bzr branch lp:mailman
+  $(py3) bzr branch lp:mailman
 
-Install and test::
+Install the Core::
 
-  $ cd mailman
-  $ python bootstrap.py
-  $ bin/buildout
-  $ bin/test
+  $(py3) cd mailman
+  $(py3) python setup.py develop
 
 If you get no errors you can now start Mailman::
 
-  $ bin/mailman start
-  $ cd ..
+  $(py3) mailman start
+  $(py3) cd ..
 
 At this point Mailman will not send nor receive any real emails.  But that's
 fine as long as you only want to work on the components related to the REST
@@ -46,31 +46,18 @@ client or the web ui.
 mailman.client (the Python bindings for Mailman's REST API)
 ===========================================================
 
-Download from Launchpad::
+Now you should switch to the virtual environment running Python version 2.6 or
+2.7.  Download the client from Launchpad::
 
-  $ bzr branch lp:mailman.client
+  $(py2) bzr branch lp:mailman.client
 
 Install in development mode to be able to change the code without working
 directly on the PYTHONPATH.
 ::
 
-  $ cd mailman.client
-  $ sudo python setup.py develop
-  $ cd ..
-
-
-Django >= 1.3
-=============
-
-Postorius is a pluggable Django application.  Therefore you need to have
-Django (at least version 1.3) installed.
-::
-
-  $ wget http://www.djangoproject.com/download/1.3.1/tarball/ -O Django-1.3.1.tar.gz
-  $ tar xzf Django-1.3.1.tar.gz
-  $ cd Django-1.3.1
-  $ sudo python setup.py install
-  $ cd ..
+  $(py2) cd mailman.client
+  $(py2) sudo python setup.py develop
+  $(py2) cd ..
 
 
 Postorius
@@ -78,19 +65,21 @@ Postorius
 
 ::
 
-  $ bzr branch lp:postorius
-  $ cd postorius
-  $ sudo python setup.py develop
+  $(py2) bzr branch lp:postorius
+  $(py2) cd postorius
+  $(py2) sudo python setup.py develop
 
 
 Start the development server
 ============================
 
-::
+Postorius is a Django app which can be used with any Django project.  We have
+a project already developed which you can set up like this::
 
-  $ cd dev_setup
-  $ python manage.py syncdb
-  $ python manage.py runserver
+  $(py2) bzr branch lp:~mailman-coders/postorius/postorius_standalone
+  $(py2) cd postorius_standalone
+  $(py2) python manage.py syncdb
+  $(py2) python manage.py runserver
 
 The last command will start the dev server on http://localhost:8000.