Merge lp:~raj-abhilash1/mailman/docs into lp:mailman

[Abhilash Raj]

Update the documentation for Setting up postorius(WebUIin5.rst)

[lp:~raj-abhilash1/mailman/docs]

7289. By Barry Warsaw on 2015-01-20

 * Fix calculation of default configuration file to use when the ``$var_dir``
   is created by ``mailman start``. (LP: #1411435)

7290. By Barry Warsaw on 2015-01-20

Fix autonumbering in style guide.

[Barry Warsaw (barry)]

Thanks! I made a few stylistic and typo modifications, and I found that I had to be in a built virtualenv in order to run the alembic command. I updated the documentation to reflect that and will commit this change. Then I'll commit a schema migration if I can get that working. Thanks for the added docs!

review: Approve

[lp:~raj-abhilash1/mailman/docs]

7291. By Barry Warsaw on 2015-01-20

 * Improve the documentation describing how to run Alembic to add new schema
   migrations. Given by Abhilash Raj.

=== modified file 'src/mailman/database/alembic/env.py'
--- src/mailman/database/alembic/env.py	2015-01-05 01:22:39 +0000
+++ src/mailman/database/alembic/env.py	2015-01-17 17:53:23 +0000
@@ -25,11 +25,18 @@
 
 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 @@
     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 @@
     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()

=== modified file 'src/mailman/docs/DATABASE.rst'
--- src/mailman/docs/DATABASE.rst	2014-11-09 12:52:58 +0000
+++ src/mailman/docs/DATABASE.rst	2015-01-17 17:53:23 +0000
@@ -59,8 +59,31 @@
 My thanks to Stephen A. Goss for his contribution of PostgreSQL support.
 
 
+Database Migrations
+===================
+
+Mailman uses `Alembic`_ to manage database migrations. Lets say you change
+something in the models, what steps are needed to reflect that change in
+the database schema? All you need to do is run this command::
+
+    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/

=== modified file 'src/mailman/docs/WebUIin5.rst'
--- src/mailman/docs/WebUIin5.rst	2012-10-31 16:31:12 +0000
+++ src/mailman/docs/WebUIin5.rst	2015-01-17 17:53:23 +0000
@@ -7,11 +7,13 @@
 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 (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 @@
 First download the latest revision of Mailman 3 from Launchpad.
 ::
 
-  $ bzr branch lp:mailman
-
-Install and test::
-
-  $ cd mailman
-  $ python bootstrap.py
-  $ bin/buildout
-  $ bin/test
+  $(py3) bzr branch lp:mailman
+
+Install the Core::
+
+  $(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 @@
 mailman.client (the Python bindings for Mailman's REST API)
 ===========================================================
 
+Now you should switch to the virtual environment running Python version 2.6
 Download 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 @@
 
 ::
 
-  $ 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
 ============================
 
-::
+Since postorius is a django app which can be used with any django project. We
+have an project already developed which you can setup 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.