Document config for migration files timestamp prefixed

See discussion in issue: https://github.com/sqlalchemy/alembic/issues/1011

### Description

Summary of changes:

* updated `alembic.ini` templates
* updated tutorial accordingly

### Checklist

This pull request is:

- [x] A documentation / typographical error fix
- [ ] A short code fix
- [ ] A new feature implementation

Closes: #1013
Pull-request: https://github.com/sqlalchemy/alembic/pull/1013
Pull-request-sha: 34f06ac0a59a6207cf132f9ae5fdc9bc4780f404

Change-Id: Ia51441c9ec39a43a0ecc1270a40859af014b326c

diff --git a/alembic/templates/async/alembic.ini.mako b/alembic/templates/async/alembic.ini.mako
index 9afeb2d2940500d91e3f38681b3414659197967f..5268e7cd7184d7ccb49fcfd31248a21b144d50ff 100644 (file)
--- a/alembic/templates/async/alembic.ini.mako
+++ b/alembic/templates/async/alembic.ini.mako
@@ -4,8 +4,9 @@
 # path to migration scripts
 script_location = ${script_location}
 
-# template used to generate migration files
-# file_template = %%(rev)s_%%(slug)s
+# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+# Uncomment the line below if you want the files to be prepended with date and time
+# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
 
 # sys.path path, will be prepended to sys.path if present.
 # defaults to the current working directory.

diff --git a/alembic/templates/generic/alembic.ini.mako b/alembic/templates/generic/alembic.ini.mako
index 9afeb2d2940500d91e3f38681b3414659197967f..5268e7cd7184d7ccb49fcfd31248a21b144d50ff 100644 (file)
--- a/alembic/templates/generic/alembic.ini.mako
+++ b/alembic/templates/generic/alembic.ini.mako
@@ -4,8 +4,9 @@
 # path to migration scripts
 script_location = ${script_location}
 
-# template used to generate migration files
-# file_template = %%(rev)s_%%(slug)s
+# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+# Uncomment the line below if you want the files to be prepended with date and time
+# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
 
 # sys.path path, will be prepended to sys.path if present.
 # defaults to the current working directory.

diff --git a/alembic/templates/multidb/alembic.ini.mako b/alembic/templates/multidb/alembic.ini.mako
index 80c8d9fb4a32aefe4a1155c77a1fd893e7e9bc8a..37376b2fdb9e496bb2dae8374fa097190870f823 100644 (file)
--- a/alembic/templates/multidb/alembic.ini.mako
+++ b/alembic/templates/multidb/alembic.ini.mako
@@ -4,8 +4,9 @@
 # path to migration scripts
 script_location = ${script_location}
 
-# template used to generate migration files
-# file_template = %%(rev)s_%%(slug)s
+# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+# Uncomment the line below if you want the files to be prepended with date and time
+# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
 
 # sys.path path, will be prepended to sys.path if present.
 # defaults to the current working directory.

diff --git a/alembic/templates/pylons/alembic.ini.mako b/alembic/templates/pylons/alembic.ini.mako
index bb425a600243f807f33e20c99a8c1a60abc59d4c..ed930dafc8d067dabaddc02b159c7c2579270524 100644 (file)
--- a/alembic/templates/pylons/alembic.ini.mako
+++ b/alembic/templates/pylons/alembic.ini.mako
@@ -4,8 +4,9 @@
 # path to migration scripts
 script_location = ${script_location}
 
-# template used to generate migration files
-# file_template = %%(rev)s_%%(slug)s
+# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+# Uncomment the line below if you want the files to be prepended with date and time
+# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
 
 # sys.path path, will be prepended to sys.path if present.
 # defaults to the current working directory.

diff --git a/docs/build/tutorial.rst b/docs/build/tutorial.rst
index 83b31ec2e4dba37aca8d2d5ae0cdeb48554df861..cbf771cd2cdc431eb270b4df8b32904e82cfbdf3 100644 (file)
--- a/docs/build/tutorial.rst
+++ b/docs/build/tutorial.rst
@@ -130,8 +130,9 @@ The file generated with the "generic" configuration looks like::
     # path to migration scripts
     script_location = alembic
 
-    # template used to generate migration files
-    # file_template = %%(rev)s_%%(slug)s
+    # template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+    # Uncomment the line below if you want the files to be prepended with date and time
+    # file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
 
     # sys.path path, will be prepended to sys.path if present.
     # defaults to the current working directory.
@@ -265,8 +266,11 @@ This file contains the following features:
   URI which contains colons is interpreted here as a resource name, rather than
   a straight filename.
 
-* ``file_template`` - this is the naming scheme used to generate new migration files.
-  The value present is the default, so is commented out.   Tokens available include:
+* ``file_template`` - this is the naming scheme used to generate new migration
+  files. Uncomment the presented value if you would like the migration files to
+  be prepended with date and time, so that they are listed in chronological
+  order.  The default value is ``%%(rev)s_%%(slug)s``.  Tokens available
+  include:
 
     * ``%%(rev)s`` - revision id
     * ``%%(slug)s`` - a truncated string derived from the revision message