- move to 0.3 as we are changing APIrel_0_3_0

- [general] The focus of 0.3 is to clean up
  and more fully document the public API of Alembic,
  including better accessors on the MigrationContext
  and ScriptDirectory objects.  Methods that are
  not considered to be public on these objects have
  been underscored, and methods which should be public
  have been cleaned up and documented, including:

    MigrationContext.get_current_revision()
    ScriptDirectory.iterate_revisions()
    ScriptDirectory.get_current_head()
    ScriptDirectory.get_heads()
    ScriptDirectory.get_base()
    ScriptDirectory.generate_revision()

- [feature] Added a bit of autogenerate to the
  public API in the form of the function
  alembic.autogenerate.compare_metadata.

1 files changed, 30 insertions, 0 deletions

diff --git a/docs/build/front.rst b/docs/build/front.rst
index bbc6437..cee535c 100644
--- a/docs/build/front.rst
+++ b/docs/build/front.rst
@@ -50,6 +50,36 @@ is installed, in addition to other dependencies.  Alembic will work with
 SQLAlchemy as of version **0.6**, though with a limited featureset.  
 The latest version of SQLAlchemy within the **0.7** series is strongly recommended.
 
+Upgrading from Alembic 0.2 to 0.3
+=================================
+
+Alembic 0.3 is mostly identical to version 0.2 except for some API
+changes, allowing better programmatic access and less ambiguity 
+between public and private methods.   In particular:
+
+* :class:`.ScriptDirectory` now features these methods - the old
+  versions have been removed unless noted:
+
+  * :meth:`.ScriptDirectory.iterate_revisions()`
+  * :meth:`.ScriptDirectory.get_current_head()` (old name ``_current_head`` is available)
+  * :meth:`.ScriptDirectory.get_heads()`
+  * :meth:`.ScriptDirectory.get_base()`
+  * :meth:`.ScriptDirectory.generate_revision()`
+  * :meth:`.ScriptDirectory.get_revision()` (old name ``_get_rev`` is available)
+  * :meth:`.ScriptDirectory.as_revision_number()` (old name ``_as_rev_number`` is available)
+
+* :meth:`.MigrationContext.get_current_revision()` (old name ``_current_rev`` remains available)
+
+* Methods which have been made private include ``ScriptDirectory._copy_file()``,
+  ``ScriptDirectory._generate_template()``, ``ScriptDirectory._upgrade_revs()``,
+  ``ScriptDirectory._downgrade_revs()``.   ``autogenerate._produce_migration_diffs``.
+  It's pretty unlikely that end-user applications
+  were using these directly.
+
+See the newly cleaned up :ref:`api` documentation for what are hopefully clearly
+laid out use cases for API usage, particularly being able to get at the revision
+information in a database as well as a script directory.
+
 Upgrading from Alembic 0.1 to 0.2
 =================================