doc for alembic + same config file as pyramid

alembic.ini

@@ -1,74 +0,0 @@
-# A generic, single database configuration.
-
-[alembic]
-# path to migration scripts
-script_location = tracim/migration
-
-# template used to generate migration files
-# file_template = %%(rev)s_%%(slug)s
-
-# timezone to use when rendering the date
-# within the migration file as well as the filename.
-# string value is passed to dateutil.tz.gettz()
-# leave blank for localtime
-# timezone =
-
-# max length of characters to apply to the
-# "slug" field
-#truncate_slug_length = 40
-
-# set to 'true' to run the environment during
-# the 'revision' command, regardless of autogenerate
-# revision_environment = false
-
-# set to 'true' to allow .pyc and .pyo files without
-# a source .py file to be detected as revisions in the
-# versions/ directory
-# sourceless = false
-
-# version location specification; this defaults
-# to migrate/versions.  When using multiple version
-# directories, initial revisions must be specified with --version-path
-# version_locations = %(here)s/bar %(here)s/bat migrate/versions
-
-# the output encoding used when revision files
-# are written from script.py.mako
-# output_encoding = utf-8
-
-sqlalchemy.url = sqlite:///%(here)s/tracim.sqlite
-
-
-# Logging configuration
-[loggers]
-keys = root,sqlalchemy,alembic
-
-[handlers]
-keys = console
-
-[formatters]
-keys = generic
-
-[logger_root]
-level = WARN
-handlers = console
-qualname =
-
-[logger_sqlalchemy]
-level = WARN
-handlers =
-qualname = sqlalchemy.engine
-
-[logger_alembic]
-level = INFO
-handlers =
-qualname = alembic
-
-[handler_console]
-class = StreamHandler
-args = (sys.stderr,)
-level = NOTSET
-formatter = generic
-
-[formatter_generic]
-format = %(levelname)-5.5s [%(name)s] %(message)s
-datefmt = %H:%M:%S

development.ini.sample

@@ -175,13 +175,50 @@ wsgidav.config_path = %(here)s/wsgidav.conf
 use = egg:waitress#main
 listen = localhost:6543
 
+[alembic]
+# path to migration scripts
+script_location = tracim/migration
+
+# template used to generate migration files
+# file_template = %%(rev)s_%%(slug)s
+
+# timezone to use when rendering the date
+# within the migration file as well as the filename.
+# string value is passed to dateutil.tz.gettz()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the
+# "slug" field
+#truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; this defaults
+# to migrate/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path
+# version_locations = %(here)s/bar %(here)s/bat migrate/versions
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+sqlalchemy.url = sqlite:///%(here)s/tracim.sqlite
+
 ###
 # logging configuration
 # https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
 ###
 
 [loggers]
-keys = root, tracim, sqlalchemy
+keys = root, tracim, sqlalchemy, alembic
 
 [handlers]
 keys = console
@@ -206,6 +243,11 @@ qualname = sqlalchemy.engine
 # "level = DEBUG" logs SQL queries and results.
 # "level = WARN" logs neither.  (Recommended for production systems.)
 
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
 [handler_console]
 class = StreamHandler
 args = (sys.stderr,)
@@ -214,3 +256,4 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
+datefmt = %H:%M:%S

doc/migration.md

@@ -0,0 +1,37 @@
+# Performing migrations #
+
+## Introduction ##
+
+This document is intended to developers.
+
+Migrations on `Tracim` lays on [`alembic`](http://alembic.zzzcomputing.com/en/latest/index.html) which is the migration tool dedicated to `SQLAlchemy`.
+
+In order to use the `alembic` commands, change your current directory to be `tracim/` from the root of the project, also usually named `tracim/` 
+and active the Tracim virtualenv:
+
+    user@host:~/tracim_backend$ cd tracim/
+    user@host:~/tracim_backend/tracim$ source env/bin/activate
+    (env) user@host:~/tracim_backend/tracim$
+
+## Migration howto - Overview ##
+   
+### Upgrading schema to last revision ###
+
+    alembic -c development.ini upgrade head
+
+### Downgrading schema ###
+
+    alembic -c development.ini downgrade -1
+
+## Migration howto - Advanced (for developers) ##
+
+### Retrieving schema current version ###
+
+    alembic -c development.ini current
+
+### Creating new schema migration ###
+
+This creates a new auto-generated python migration file 
+in `tracim/migration/versions/` ending by `migration_label.py`:
+
+    alembic -c development.ini revision --autogenerate -m "migration label"