Rev 3481: Add Bazaar Zen section to User Guide (Ian Clatworthy) in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Fri Jun 6 13:29:25 BST 2008
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 3481
revision-id:pqm at pqm.ubuntu.com-20080606122916-jpq5b5yt1bv9hvsz
parent: pqm at pqm.ubuntu.com-20080606084412-dhc7evfuhlcth4h2
parent: ian.clatworthy at canonical.com-20080606120248-qibdc6mzqrdeq3hg
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Fri 2008-06-06 13:29:16 +0100
message:
Add Bazaar Zen section to User Guide (Ian Clatworthy)
renamed:
doc/en/user-guide/revnos.txt => doc/en/user-guide/zen.txt revnos.txt-20080111231928-pbntxea0ynh9ww1t-1
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
doc/en/user-guide/core_concepts.txt core_concepts.txt-20071114035000-q36a9h57ps06uvnl-2
doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2
doc/en/user-guide/zen.txt revnos.txt-20080111231928-pbntxea0ynh9ww1t-1
------------------------------------------------------------
revno: 3480.1.1
revision-id:ian.clatworthy at canonical.com-20080606120248-qibdc6mzqrdeq3hg
parent: pqm at pqm.ubuntu.com-20080606084412-dhc7evfuhlcth4h2
parent: ian.clatworthy at canonical.com-20080606115558-qw0kh7p3dl1o6o9s
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
branch nick: ianc-integration
timestamp: Fri 2008-06-06 22:02:48 +1000
message:
Add Bazaar Zen section to User Guide (Ian Clatworthy)
renamed:
doc/en/user-guide/revnos.txt => doc/en/user-guide/zen.txt revnos.txt-20080111231928-pbntxea0ynh9ww1t-1
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
doc/en/user-guide/core_concepts.txt core_concepts.txt-20071114035000-q36a9h57ps06uvnl-2
doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2
doc/en/user-guide/zen.txt revnos.txt-20080111231928-pbntxea0ynh9ww1t-1
------------------------------------------------------------
revno: 3412.1.5
revision-id:ian.clatworthy at canonical.com-20080606115558-qw0kh7p3dl1o6o9s
parent: ian.clatworthy at canonical.com-20080509154042-z1gs6y8fkc93r1nm
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
branch nick: bzr.ug-ch2
timestamp: Fri 2008-06-06 21:55:58 +1000
message:
tweaks requested by jam & poolie during review
modified:
doc/en/user-guide/zen.txt revnos.txt-20080111231928-pbntxea0ynh9ww1t-1
------------------------------------------------------------
revno: 3412.1.4
revision-id:ian.clatworthy at canonical.com-20080509154042-z1gs6y8fkc93r1nm
parent: ian.clatworthy at canonical.com-20080509145931-guspnwkwjwfay1y4
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
branch nick: bzr.ug-ch2
timestamp: Sat 2008-05-10 01:40:42 +1000
message:
incorporate feedback from Robert and John
modified:
doc/en/user-guide/zen.txt revnos.txt-20080111231928-pbntxea0ynh9ww1t-1
------------------------------------------------------------
revno: 3412.1.3
revision-id:ian.clatworthy at canonical.com-20080509145931-guspnwkwjwfay1y4
parent: ian.clatworthy at canonical.com-20080508024325-vbz4qjad3zlt2f2q
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
branch nick: bzr.ug-ch2
timestamp: Sat 2008-05-10 00:59:31 +1000
message:
improve rev number explanation using Robert's text
modified:
doc/en/user-guide/core_concepts.txt core_concepts.txt-20071114035000-q36a9h57ps06uvnl-2
------------------------------------------------------------
revno: 3412.1.2
revision-id:ian.clatworthy at canonical.com-20080508024325-vbz4qjad3zlt2f2q
parent: ian.clatworthy at canonical.com-20080507150511-knbx81nnyhzhdmrh
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
branch nick: bzr.ug-ch2
timestamp: Thu 2008-05-08 12:43:25 +1000
message:
cleanup, add summary and NEWS item
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
doc/en/user-guide/zen.txt revnos.txt-20080111231928-pbntxea0ynh9ww1t-1
------------------------------------------------------------
revno: 3412.1.1
revision-id:ian.clatworthy at canonical.com-20080507150511-knbx81nnyhzhdmrh
parent: pqm at pqm.ubuntu.com-20080507100452-ya8ofjjd5f5pb9q7
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
branch nick: bzr.ug-ch2
timestamp: Thu 2008-05-08 01:05:11 +1000
message:
add Bazaar Zen section, moving revno text into it
renamed:
doc/en/user-guide/revnos.txt => doc/en/user-guide/zen.txt revnos.txt-20080111231928-pbntxea0ynh9ww1t-1
modified:
doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2
doc/en/user-guide/zen.txt revnos.txt-20080111231928-pbntxea0ynh9ww1t-1
=== renamed file 'doc/en/user-guide/revnos.txt' => 'doc/en/user-guide/zen.txt'
--- a/doc/en/user-guide/revnos.txt 2008-01-15 21:42:00 +0000
+++ b/doc/en/user-guide/zen.txt 2008-06-06 11:55:58 +0000
@@ -1,33 +1,216 @@
-Understanding Revision Numbers
-==============================
-
-All revisions in the mainline of a branch will have a simple increasing
+Bazaar Zen
+==========
+
+Grokking Bazaar
+---------------
+
+While Bazaar is similar to other VCS tools in many ways, there are
+some important differences that are not necessarily obvious at first
+glance. This section attempts
+to explain some of the things users need to know in order to "grok" Bazaar,
+i.e. to deeply understand it.
+
+Note: It isn't necessary to fully understand this section to use Bazaar.
+You may wish to skim this section now and come back to it at a later time.
+
+Understanding revision numbers
+------------------------------
+
+All revisions in the mainline of a branch have a simple increasing
integer. (First commit gets 1, 10th commit gets 10, etc.) This makes them
fairly natural to use when you want to say "grab the 10th revision from my
branch", or "fixed in revision 3050".
-For revisions which have been merged into a branch, a dotted notation is
-used (eg, 3112.1.5). Dotted revision numbers have three numbers. The first
+For revisions which have been merged into a branch, a dotted notation is used
+(e.g., 3112.1.5). Dotted revision numbers have three numbers [#]_. The first
number indicates what mainline revision change is derived from. The second
number is the branch counter. There can be many branches derived from the
same revision, so they all get a unique number. The third number is the
number of revisions since the branch started. For example, 3112.1.5 is the
first branch from revision 3112, the fifth revision on that branch.
-Revisions are numbered in a stable way, such that if two branches have the
-same revision in their mainline, all revisions in the ancestry of that
-revision will have the same revision numbers. (So if Alice and Bob's
+.. [#] Versions prior to bzr 1.2 used a slightly different algorithm.
+ Some nested branches would get extra numbers (such as 1.1.1.1.1)
+ rather than the simpler 3-number system.
+
+Hierarchical history is good
+----------------------------
+
+Imagine a project with multiple developers contributing changes where
+many changes consist of a series of commits. To give a concrete example,
+consider the case where:
+
+ * The tip of the project's trunk is revision 100.
+ * Mary makes 3 changes to deliver feature X.
+ * Bill makes 4 changes to deliver feature Y.
+
+If the developers are working in parallel and using a traditional
+centralized VCS approach, the project history will most likely be linear
+with Mary's changes and Bill's changes interleaved. It might look like this::
+
+ 107: Add documentation for Y
+ 106: Fix bug found in testing Y
+ 105: Fix bug found in testing X
+ 104: Add code for Y
+ 103: Add documentation for X
+ 102: Add code and tests for X
+ 101: Add tests for Y
+ 100: ...
+
+Many teams use this approach because their tools make branching and merging
+difficult. As a consequence, developers update from and commit to the trunk
+frequently, minimizing integration pain by spreading it over every commit.
+If you wish, you can use Bazaar exactly like this. Bazaar does offer other
+ways though that you ought to consider.
+
+An alternative approach encouraged by distributed VCS tools is to create
+feature branches and to integrate those when they are ready. In this case,
+Mary's feature branch would look like this::
+
+ 103: Fix bug found in testing X
+ 102: Add documentation for X
+ 101: Add code and tests for X
+ 100: ...
+
+And Bill's would look like this::
+
+ 104: Add documentation for Y
+ 103: Fix bug found in testing Y
+ 102: Add code for Y
+ 101: Add tests for Y
+ 100: ...
+
+If the features were independent and you wanted to keep linear history,
+the changes could be pushed back into the trunk in batches. (Technically,
+there are several ways of doing that but that's beyond the scope of
+this discussion.) The resulting history might look like this::
+
+ 107: Fix bug found in testing X
+ 106: Add documentation for X
+ 105: Add code and tests for X
+ 104: Add documentation for Y
+ 103: Fix bug found in testing Y
+ 102: Add code for Y
+ 101: Add tests for Y
+ 100: ...
+
+While this takes a bit more effort to achieve, it has some advantages over
+having revisions randomly intermixed. Better still though, branches can
+be merged together forming a non-linear history. The result might look
+like this::
+
+ 102: Merge feature X
+ 100.2.3: Fix bug found in testing X
+ 100.2.2: Add documentation for X
+ 100.2.1: Add code and tests for X
+ 101: Merge feature Y
+ 100.1.4: Add documentation for Y
+ 100.1.3: Fix bug found in testing Y
+ 100.1.2: Add code for Y
+ 100.1.1: Add tests for Y
+ 100: ...
+
+Or more likely this::
+
+ 102: Merge feature X
+ 100.2.3: Fix bug
+ 100.2.2: Add documentation
+ 100.2.1: Add code and tests
+ 101: Merge feature Y
+ 100.1.4: Add documentation
+ 100.1.3: Fix bug found in testing
+ 100.1.2: Add code
+ 100.1.1: Add tests
+ 100: ...
+
+This is considered good for many reasons:
+
+ * It makes it easier to understand the history of a project.
+ Related changes are clustered together and clearly partitioned.
+
+ * You can easily collapse history to see just the commits on the mainline
+ of a branch. When viewing the trunk history like this, you only see
+ high level commits (instead of a large number of commits uninteresting
+ at this level).
+
+ * If required, it makes backing out a feature much easier.
+
+ * Continuous integration tools can be used to ensure that
+ all tests still pass before committing a merge to the mainline.
+ (In many cases, it isn't appropriate to trigger CI tools after
+ every single commit as some tests will fail during development.
+ In fact, adding the tests first - TDD style - will guarantee it!)
+
+In summary, the important points are:
+
+ *Organize your work using branches.*
+
+ *Integrate changes using merge.*
+
+ *Ordered revision numbers and hierarchy make history easier to follow.*
+
+
+Each branch has its own view of history
+---------------------------------------
+
+As explained above, Bazaar makes the distinction between:
+
+ * mainline revisions, i.e. ones you committed in your branch, and
+
+ * merged revisions, i.e. ones added as ancestors by committing a merge.
+
+Each branch effectively has its own view of history, i.e. different
+branches can give the same revision a different "local" revision number.
+Mainline revisions always get allocated single number revision numbers
+while merged revisions always get allocated dotted revision numbers.
+
+To extend the example above, here's what the revision history of
+Mary's branch would look like had she decided to merge the project
+trunk into her branch after completing her changes::
+
+ 104: Merge mainline
+ 100.2.1: Merge feature Y
+ 100.1.4: Add documentation
+ 100.1.3: Fix bug found in testing
+ 100.1.2: Add code
+ 100.1.1: Add tests
+ 103: Fix bug found in testing X
+ 102: Add documentation for X
+ 101: Add code and tests for X
+ 100: ...
+
+Once again, it's easy for Mary to look at just *her* top level of history
+to see the steps she has taken to develop this change. In this context,
+merging the trunk (and resolving any conflicts caused by doing that) is
+just one step as far as the history of this branch is concerned.
+
+It's important to remember that Bazaar is not changing history here, nor
+is it changing the global revision identifiers. You can always use the
+latter if you really want to. In fact, you can use the branch specific
+revision numbers when communicating *as long as* you provide the branch
+URL as context. (In many Bazaar projects, developers imply the central
+trunk branch if they exchange a revision number without a branch URL.)
+
+Merges do not change revision numbers in a branch, though they do
+allocate local revision numbers to newly merged revisions. The only time
+Bazaar will change revision numbers in a branch is when you explicitly
+ask it to mirror another branch.
+
+Note: Revisions are numbered in a stable way: if two branches have
+the same revision in their mainline, all revisions in the ancestry of that
+revision will have the same revision numbers. For example, if Alice and Bob's
branches agree on revision 10, they will agree on all revisions before
-that.) Future merges will not change revision numbers. However doing
-``bzr pull`` can change revision numbers, because it changes the
-mainline revisions.
-
-
-bzr versions < 1.2
-------------------
-Versions prior to bzr 1.2 used a slightly different algorithm. Some nested
-branches would get extra numbers (such as 1.1.1.1.1) rather than the
-simpler 3-number system.
+that.
+
+Summary
+-------
+
+In general, if you follow the advice given earlier - organise
+your work in branches and use merge to collaborate - you'll find Bazaar
+generally does what you expect.
+
+In coming chapters, we examine various ways of using Bazaar beginning with
+the simplest: using Bazaar for personal projects.
..
vim: ft=rst tw=74 ai
=== modified file 'NEWS'
--- a/NEWS 2008-06-06 08:44:12 +0000
+++ b/NEWS 2008-06-06 12:02:48 +0000
@@ -36,6 +36,10 @@
* ``bzr status`` was breaking if you merged the same revision twice.
(John Arbash Meinel, #235407)
+ DOCUMENTATION:
+
+ * Added *Bazaar Zen* section to the User Guide. (Ian Clatworthy)
+
TESTING:
* Fix the test HTTPServer to be isolated from chdir calls made while it is
=== modified file 'doc/en/user-guide/core_concepts.txt'
--- a/doc/en/user-guide/core_concepts.txt 2008-04-03 05:21:57 +0000
+++ b/doc/en/user-guide/core_concepts.txt 2008-05-09 14:59:31 +0000
@@ -35,9 +35,21 @@
pqm at pqm.ubuntu.com-20071129184101-u9506rihe4zbzyyz
-While these identifiers are necessary for internal use and external tool
-integration, branch-specific *revision numbers* are the preferred
-interface for humans. Typical revision numbers are 1, 42 and 2977.1.59.
+Revision-ids are generated at commit time or, for imports from other
+systems, at the time of import. While revision-ids are necessary
+for internal use and external tool integration, branch-specific
+*revision numbers* are the preferred interface for humans.
+
+Revision numbers are dotted decimal identifiers like 1, 42 and 2977.1.59
+that trace a path through the revision number graph for a branch.
+Revision numbers are generally shorter than revision-ids and,
+within a single branch, can be compared with each other to get a sense
+of their relationship. For example, revision 10 is the mainline (see below)
+revision immediately after revision 9. Revision numbers
+are generated on the fly when commands are executing, because they
+depend on which revision is the tip (i.e. most recent revision)
+in the branch.
+
See `Specifying revisions`_ in the appendices for a closer look at
the numerous ways that revisions and ranges of revisions can be specified
in Bazaar, and `Understanding Revision Numbers`_ for a more detailed
@@ -60,7 +72,7 @@
------
In the simplest case, a branch is an *ordered series of revisions*.
-The last revision is known as the *head*.
+The last revision is known as the *tip*.
Branches may split apart and be *merged* back together, forming a
*graph* of revisions. Technically, the graph shows directed relationships
=== modified file 'doc/en/user-guide/index.txt'
--- a/doc/en/user-guide/index.txt 2008-05-16 21:00:25 +0000
+++ b/doc/en/user-guide/index.txt 2008-06-06 12:02:48 +0000
@@ -27,11 +27,11 @@
.. include:: installing_bazaar.txt
.. include:: entering_commands.txt
-.. include:: revnos.txt
.. include:: getting_help.txt
.. include:: configuring_bazaar.txt
.. include:: using_aliases.txt
.. include:: plugins.txt
+.. include:: zen.txt
Personal version control
More information about the bazaar-commits
mailing list