diff options
author | Mike Bayer <mike_mp@zzzcomputing.com> | 2014-11-20 18:07:41 -0500 |
---|---|---|
committer | Mike Bayer <mike_mp@zzzcomputing.com> | 2014-11-20 18:07:41 -0500 |
commit | 793edec5b810632a7668e9b6e875d818b507d046 (patch) | |
tree | 46fe04c30ee7f7f72d45d5d987868889718095ff | |
parent | fac7bcf97b2f5b74ce1e74c94dacfbc7cd547d1e (diff) | |
download | alembic-793edec5b810632a7668e9b6e875d818b507d046.tar.gz |
- changelogmulti_branch
- finish up tutorial
-rw-r--r-- | docs/build/changelog.rst | 35 | ||||
-rw-r--r-- | docs/build/tutorial.rst | 67 |
2 files changed, 76 insertions, 26 deletions
diff --git a/docs/build/changelog.rst b/docs/build/changelog.rst index d343ed3..9001333 100644 --- a/docs/build/changelog.rst +++ b/docs/build/changelog.rst @@ -7,13 +7,38 @@ Changelog :version: 0.7.0 .. change:: + :tags: feature, versioning + :tickets: 167 + + The "multiple heads / branches" feature has now landed. This is + by far the most significant change Alembic has seen since its inception; + while the workflow of most commands hasn't changed, and the format + of version files and the ``alembic_version`` table are unchanged as well, + a new suite of features opens up in the case where multiple version + files refer to the same parent, or to the "base". Merging of + branches, operating across distinct named heads, and multiple + independent bases are now all supported. The feature incurs radical + changes to the internals of versioning and traversal, and should be + treated as "beta mode" for the next several subsequent releases + within 0.7. + + .. seealso:: + + :ref:`branches` + + .. change:: :tags: feature, commands - New commands added: ``alembic show``and ``alembic merge``. Also, - a new option ``--verbose`` has been added to several informational - commands, such as ``alembic current``, ``alembic branches``, and - ``alembic heads``. ``alembic revision`` also contains several new - options used within the new branch management system. + New commands added: ``alembic show``, ``alembic heads`` and + ``alembic merge``. Also, a new option ``--verbose`` has been + added to several informational commands, such as ``alembic history``, + ``alembic current``, ``alembic branches``, and ``alembic heads``. + ``alembic revision`` also contains several new options used + within the new branch management system. The output of commands has + been altered in many cases to support new fields and attributes; + the ``history`` command in particular now returns it's "verbose" output + only if ``--verbose`` is sent; without this flag it reverts to it's + older behavior of short line items (which was never changed in the docs). .. change:: :tags: changed, commands diff --git a/docs/build/tutorial.rst b/docs/build/tutorial.rst index 7d5900f..84297f1 100644 --- a/docs/build/tutorial.rst +++ b/docs/build/tutorial.rst @@ -1382,10 +1382,20 @@ Working with Branches .. versionadded:: 0.7.0 -A **branch** describes when a source tree is broken up into two versions representing -two independent sets of changes. The challenge of a branch is to **merge** the -branches into a single series of changes. Alembic's GUID-based version number scheme -allows branches to be reconciled. +A **branch** describes a point in a migration stream when two or more +versions refer to the same parent migration as their anscestor. Branches +occur naturally when two divergent source trees, both containing Alembic +revision files created independently within those source trees, are merged +together into one. When this occurs, the challenge of a branch is to **merge** the +branches into a single series of changes, so that databases established +from either source tree individually can be upgraded to reference the merged +result equally. Another scenario where branches are present are when we create them +directly; either at some point in the migration stream we'd like different +series of migrations to be managed independently (e.g. we create a tree), +or we'd like separate migration streams for different features starting +at the root (e.g. a *forest*). We'll illustrate all of these cases, starting +with the most common which is a source-merge-originated branch that we'll +merge. Starting with the "account table" example we began in :ref:`create_migration`, assume we have our basemost version ``1975ea83b712``, which leads into @@ -1405,7 +1415,7 @@ Both it, as well as ``ae1027a6acf_add_a_column.py``, reference # branched source tree 1975ea83b712 (add account table) -> 27c6a30d7c24 (add shopping cart table) -Above, we can see 1975ea83b712 is our **branch point**; two distinct versions +Above, we can see ``1975ea83b712`` is our **branch point**; two distinct versions both refer to it as its parent. The Alembic command ``branches`` illustrates this fact:: @@ -1488,7 +1498,7 @@ We create the merge file using ``alembic merge``; with this command, we can pass to it an argument such as ``heads``, meaning we'd like to merge all heads. Or, we can pass it individual revision numbers sequentally:: - python -m alembic.config merge -m "merge ae1 and 27c" ae1027 27c6a + $ alembic merge -m "merge ae1 and 27c" ae1027 27c6a Generating /path/to/foo/versions/53fffde5ad5_merge_ae1_and_27c.py ... done Looking inside the new file, we see it as a regular migration file, with @@ -1546,7 +1556,7 @@ History shows a similar result, as the mergepoint becomes our head:: 1975ea83b712 -> 27c6a30d7c24, add shopping cart table <base> -> 1975ea83b712 (branchpoint), add account table -With a single ``head`` target, a generic ``upgrade `` can proceed:: +With a single ``head`` target, a generic ``upgrade`` can proceed:: $ alembic upgrade head INFO [alembic.migration] Context impl PostgresqlImpl. @@ -1612,7 +1622,7 @@ With a single ``head`` target, a generic ``upgrade `` can proceed:: Revises: 1975ea83b712 Create Date: 2014-11-20 13:03:11.436407 - A key advantage to the ``merge`` process is that this merge process will + A key advantage to the ``merge`` process is that it will run equally well on databases that were present on version ``ae1027a6acf`` alone, versus databases that were present on version ``27c6a30d7c24`` alone; whichever version was not yet applied, will be applied before the merge point @@ -1741,7 +1751,7 @@ label applied to this revision:: 1975ea83b712 -> ae1027a6acf (head), add a column <base> -> 1975ea83b712 (branchpoint), add account table -With the label applied the name ``shoppingcart`` now serves as an alias +With the label applied, the name ``shoppingcart`` now serves as an alias for the ``27c6a30d7c24`` revision specifically. We can illustrate this by showing it with ``alembic show``:: @@ -1823,6 +1833,16 @@ revision in our listing as well. The ``<branchname>@base`` syntax can be useful when we are dealing with individual bases, as we'll see in the next section. +The ``<branchname>@head`` format can also be used with revision numbers +instead of branch names, though this is less convenient. If we wanted to +add a new revision to our branch that includes the un-labeled ``ae1027a6acf``, +if this weren't a head already, we could ask for the "head of the branch +that includes ``ae1027a6acf``" as follows:: + + $ alembic revision -m "add another account column" --head ae10@head + Generating /Users/classic/dev/alembic/foo/versions/55af2cb1c267_add_another_account_column.py ... done + + Working with Multiple Bases --------------------------- @@ -1832,7 +1852,7 @@ if we have multiple heads, ``alembic revision`` allows us to tell it which allow us to assign names to branches that we can use in subsequent commands. Let's put all these together and refer to a new "base", that is, a whole new tree of revision files that will be semi-independent of the account/shopping -cart tables we've been working with. +cart revisions we've been working with. Creating a Labeled Base Revision ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1898,16 +1918,19 @@ we didn't mean to specify the head:: FAILED: Revision 3782d9986ced is not a head revision; please specify --splice to create a new branch from this revision -The ``<branchname>@head`` format can also be used with revision numbers -instead of branch names, though this is less convenient. If we wanted to -add a new revision to our branch that includes the un-labeled ``ae1027a6acf``, -if this weren't a head already, we could ask for the "head of the branch -that includes ``ae1027a6acf``" as follows:: +As mentioned earlier, as this base is independent, we can view its history +from the base using ``history -r networking@base:``:: + + $ alembic history -r networking@base: + 109ec7d132bf -> 29f859a13ea (networking) (head), add DNS table + 3782d9986ced -> 109ec7d132bf (networking), add ip number table + <base> -> 3782d9986ced (networking), create networking branch + +Note this is the same output we'd get at this point if we used +``-r :networking@head``. - $ alembic revision -m "add another account column" --head ae10@head - Generating /Users/classic/dev/alembic/foo/versions/55af2cb1c267_add_another_account_column.py ... done -We have quite a lot of versioning going on, history now shows:: +We have quite a lot of versioning going on, history overall now shows:: $ alembic history 109ec7d132bf -> 29f859a13ea (networking) (head), add DNS table @@ -1936,7 +1959,7 @@ or against the whole thing using ``heads``:: INFO [alembic.migration] Running upgrade 1975ea83b712 -> ae1027a6acf, add a column INFO [alembic.migration] Running upgrade ae1027a6acf -> 55af2cb1c267, add another account column -If you actually wanted it, all three branches can be merged:: +If you actually wanted, all three branches can be merged:: $ alembic merge -m "merge all three branches" heads Generating /Users/classic/dev/alembic/foo/versions/3180f4d6e81d_merge_all_three_branches.py ... done @@ -1981,8 +2004,10 @@ unnamed ``ae1027a6acf`` branch since we've merged everything together. <base> -> 1975ea83b712 (branchpoint), add account table It follows then that the "branch labels" feature is useful for branches -that are **unmerged**. Once branches are merged into a single stream, the -usefulness of labels is not as apparent. +that are **unmerged**. Once branches are merged into a single stream, labels +are not particularly useful as they tend to refer to the whole revision +stream in any case. They can of course be removed from revision files +at the point at which they are no longer useful, or moved to other files. For posterity, here's the graph of the whole thing:: |