New FAQ entry re bzr

[Edward K. Ream]

Ville recently reposted (to an ipython list) his tutorial about how to
use bzr. I copied it to Leo's FAQ:

http://webpages.charter.net/edreamleo/FAQ.html#how-do-i-use-bzr-to-get-the-latest-sources-from-leo-s-launchpad-site

And it's in LeoDocs.leo on the trunk. Thanks Ville for this very
clear explanation.

Edward

[TL]

The bzr FAQ does a nice job describing the work flow based on a
"Hosted" branch which is peer reviewed and then merged into the
trunk. What about small code changes or documentation changes?
Should these type of changes also follow the peer-reviewed work flow
described in the FAQ or should there be an alternate work flow that
enables developers to update the trunk directly from a local branch?
Section 6.2.5 of the Bazaar User Guide discribes a workflow that
should do the job but I had problems with it today when I tried to
update the trunk with a simple fix to the mod_tempfname.py plugin
file.

6.2.5 Merging a feature into the trunk
bzr pull
bzr merge ../X-fix-123
(resolve any conflicts)
bzr commit -m "Fixed bug #123"
bzr push

[Terry Brown]

I think push is inherently dangerous - you should only ever need to use
it once on a launch pad branch, to create the branch.

After that I'd use a bound checkout, so that when you commit bzr checks
for changes and refuses to do anything until they're merged.

bzr init-repo leo.repo
cd leo.repo

bzr checkout
bzr+ssh://terry-...@bazaar.launchpad.net/%7Eleo-editor-team/leo-editor/trunk

(all that on one line, creates local copy of trunk)

branch trunk myNewCode

(very fast because of shared files in leo.repo, at this point directory
structure is:

leo.repo
trunk
leo
core
plugins
...
myNewCode
leo
core
plugins
...

(hack / commit / hack / commit / etc. in myNewCode)

if you want, probably a good idea:

bzr merge
http://bazaar.launchpad.net/%7Eleo-editor-team/leo-editor/trunk

in myNewCode to keep up with trunk.

When you're ready to commit changes to the trunk

cd trunk
bzr update

bzr merge ../myNewCode

(test)

bzr commit

this last line sends the changes to launchpad, but only if nothing's
changed there.

There are other orders which have the same effect - i.e. using commit
rather than push to send things to launch pad.

Cheers -Terry

[Edward K. Ream]

On Tue, Jun 3, 2008 at 10:20 PM, Terry Brown <terry_...@yahoo.com> wrote:

I think push is inherently dangerous - you should only ever need to use
it once on a launch pad branch, to create the branch.

Fernando has been complaining on ipython-dev about weird history stuff when using push. 

I'm getting pretty confused about bzr.  I use push all the time to send stuff to the trunk, but bzr has so many ways of doing things that I don't really understand the implications of what I am doing.

For the record, my work flow is:

make changes
bzr commit -m "describe change" each-file
bzr push

If the trunk contains other changes, then before the push I do:

bzr merge
bzr recommit  # synonym for bzr commit -m "recommit after merge"

Edward

[TL]

Thanks Terry and Edward for publishing your bzr workflows. Very
helpful!

TL

[TL]

Using Terry's work flow with a local repository, I committed the
leoSettings.leo file with a couple of vi emulator changes as revision
509. Later, with Edwards updates the leoSettings.leo changes moved to
revision 511 and the revision description that I entered is gone.

Why is this happening? I think we need to find a work flow that will
avoid this from happening. We're losing historical documentation,
we're having to spend time to verify that changes haven't been lost,
and confusion will occur if forum posts reference a change in a
specific revision and then the change moves to a later version.

TL

[Terry Brown]

I suspect that they're not actually gone, just the revision numbers change... yes, that sounds crazy, but if everyone starts with rev 505 and does some stuff and commits on after another you can't all get 506... even though on your local trunk, before the commit, that's what you'd seem to have.

View the output from `bzr log` and I think you'll find your commit messages in there, somewhere. With revision numbers like 504.3.1

Cheers -Terry

--- On Fri, 6/6/08, TL <t...@tltools.net> wrote:

[Edward K. Ream]

On Fri, Jun 6, 2008 at 6:08 PM, TL <t...@tltools.net> wrote:

Using Terry's work flow with a local repository, I committed the
leoSettings.leo file with a couple of vi emulator changes as revision
509.  Later, with Edwards updates the leoSettings.leo changes moved to
revision 511 and the revision description that I entered is gone.

As Terry said, your work is there, with another rev number.  I just did the following:

QQQQ
C:\leo.repo\trunk>bzr log
------------------------------------------------------------
revno: 511
committer: Edward K. Ream <edre...@gmail.com>
branch nick: trunk
timestamp: Fri 2008-06-06 09:07:54 -0500
message:
  commit after merge
    ------------------------------------------------------------
    revno: 507.2.2
    committer: TL <T...@TLTooLs.net>
    branch nick: trunk
    timestamp: Fri 2008-06-06 07:39:25 -0500
    message:
      Vi emulation - Fixed outline's delete line 'dd'.  Added 'dD' for testing.
        ------------------------------------------------------------
        revno: 507.1.2
        committer: TL <T...@TLTooLs.net>
        branch nick: vi
        timestamp: Fri 2008-06-06 07:29:08 -0500
        message:
          Vi emulation - Outline's 'dd' command fixed.  'dD' added for testing.
    ------------------------------------------------------------
    revno: 507.2.1
    committer: TL <T...@TLTooLs.net>
    branch nick: trunk
    timestamp: Thu 2008-06-05 21:27:10 -0500
    message:
      Merge with trunk
    ------------------------------------------------------------
    revno: 507.1.1
    committer: TL <T...@TLTooLs.net>
    branch nick: vi
    timestamp: Thu 2008-06-05 21:18:22 -0500
    message:
      Modified vi's tree bindings to support 'delete line' function (bind: 'dd')
------------------------------------------------------------
revno: 510
committer: Edward K. Ream <edre...@gmail.com>
branch nick: trunk
timestamp: Fri 2008-06-06 09:05:43 -0500
message:
  update aux files
------------------------------------------------------------
revno: 509
committer: Edward K. Ream <edre...@gmail.com>
branch nick: trunk
timestamp: Fri 2008-06-06 09:05:18 -0500
message:
  call g.chdir after most file/import/export commands
------------------------------------------------------------
revno: 508
committer: Edward K. Ream <edre...@gmail.com>
branch nick: trunk
timestamp: Fri 2008-06-06 09:03:02 -0500
message:
  added g.chdir
------------------------------------------------------------
revno: 507
committer: Edward K. Ream <edre...@gmail.com>
branch nick: trunk
timestamp: Thu 2008-06-05 13:16:24 -0500
message:
  update aux files
C:\leo.repo\trunk>
QQQQ

I just check the bzr users guide and reference, and there doesn't seem to be a discussion of version numbers after merges.  This is a very confusing hole in the docs.

Here is a transcript of my comments on #bzr

QQQQQQ
(06:05:34) edreamleo: Hello all. bzr version numbers after merges are causing great confusion with the Leo and IPython projects. Somebody on the Leo project said "if everyone starts with rev 505 and does some stuff and commits on after another you can't all get 506." which makes sense to me. Is this issues documented anywhere? If not, I think you could help lots of people, including me, if you did so.
(06:07:20) mathrick: edreamleo: no, each of the trees will have its own rev 505
(06:07:40) mathrick: depending on how you merge, the other "505s" will end up as different revisions in your tree
(06:08:00) mathrick: revno is only meaningful for a single tree
(06:08:15) mathrick: what matters cross-tree is that the revisions are the same
(06:08:21) LarstiQ: mathrick: before there was rich root support, all the root ids (fileid of /) were TREE_ROOT
(06:10:25) edreamleo: mathrick: it seems that rev numbers aren't documented. It would be "soothing" to newbies if we could understand where rev numbers like 507.2.2 came from. True, bzr log does show the renumbered branches, but I think a discussion in the docs somewhere would help.
LarstiQ: edreamleo: revnos are determined by the lefthand side ('mainline') of the revision DAG of a branch

LarstiQ: edreamleo: as an aside, revids (and not revnos) globally uniquely define a revision. See bzr log --show-ids for example
(06:14:15) mathrick: edreamleo: hmm, is that really an issue? It only shows up in commit logs for merge revisions, where you can immediately see it's a merge
(06:14:47) LarstiQ: edreamleo: Merged revisions, the indented ones in bzr log output, get dotted revnos, the first number is the same as the revno of the revision in the current branch where they branched from.
(06:18:03) edreamleo: mathrick: It's "really" an issue only in the sense that it confuses newbies. True, the log is about as clear as it could be. The problem is, that newbies think there recently committed changes went away, depending on what the "main" revno is, and newbies then don't think to look at the log. I strongly suspect the revnums are fine, it's just a learning problem with bzr. But I know for sure that it is confusing for several sets of newbies.
(06:23:38) mathrick: edreamleo: ah, so you mean they branch at 504, commit "foo" at 505, merge someone else's tree where 505 is "bar", then wonder why they still don't have the bar in their tree, since 505 is "foo"?
(06:25:22) edreamleo: mathrick: yes, I believe that something like that is what is confusing folks.
(06:25:55) mathrick: edreamleo: that is a problem when you think of "the" repo and checkouts, instead of a set of DAGs
(06:26:01) edreamleo: To repeat, once people think to look at the log they are probably going to be reassured
(06:26:26) mathrick: edreamleo: however, how do they find out 505 is "foo" and not "bar" if not through the log?
(06:26:33) edreamleo: Interesting. Afaik, dag's are never mentioned in the docs.
(06:28:19) mathrick: I guess a little technical aside mentioning DAGs and how trees being DAGs means they can be non-identical yet equivalent could help
(06:28:45) edreamleo: mathrick: here is the original report on http://groups.google.com/group/leo-editor
(06:29:20) edreamleo: I committed the leoSettings.leo file with a couple of vi emulator changes as revision 509.
(06:29:47) edreamleo: Later, with Edwards updates the leoSettings.leo changes moved to revision 511 and the revision description that I entered is gone.
(06:30:12) edreamleo: That's the essence of the report. Does that make any sense to you? I'm totally confused :-)
(06:30:56) mathrick: edreamleo: this one? http://groups.google.com/group/leo-editor/browse_thread/thread/a207aa1ba5247363
(06:31:27) edreamleo: mathrick: yes, that's the thread
(06:32:33) mathrick: edreamleo: ok, did you commit on a branch and pushed, or committed on a checkout?
(06:32:49) edreamleo: my workflow is to commit and push
(06:32:50) mathrick: the two look similar, but are fundamentally different when it comes to commits
(06:33:41) mathrick: edreamleo: aha, then indeed you will never get the same revnos if there's been intermediate traffic on the target branch
(06:33:52) mathrick: edreamleo: can I have your mainline branch URL?
(06:35:16) edreamleo: mathrick: https://code.launchpad.net/~leo-editor-team/leo-editor/trunk
(06:38:11) mathrick: edreamleo: ah, yes, I suppose you have looked at the log already?
(06:38:23) mathrick: if no, bzr log https://code.launchpad.net/~leo-editor-team/leo-editor/trunk | less
(06:38:58) LarstiQ: edreamleo: http://doc.bazaar-vcs.org/latest/en/user-guide/index.html#understanding-revision-numbers
(06:39:26) LarstiQ: edreamleo: and also 1.2.2, http://doc.bazaar-vcs.org/latest/en/user-guide/index.html#id19
(06:40:56) edreamleo: LarstiQ: thanks for these urls!
(06:41:22) mathrick: LarstiQ: I suppose specifically mentioning implications of merges in http://doc.bazaar-vcs.org/latest/en/user-guide/index.html#understanding-revision-numbers would help, tho
(06:41:23) LarstiQ: edreamleo: np :)
(06:41:23) edreamleo: mathrick: Aha. I have only looked at my local log...
QQQQQQ

[Edward K. Ream]

On Sat, Jun 7, 2008 at 6:50 AM, Edward K. Ream <edre...@gmail.com> wrote:

Here is a transcript of my comments on #bzr

[snip]

One more comment:

LarstiQ: edreamleo: the key thing to take away here is that what uniquely identifies a revision is the revision _id_ (revid for short, example: p...@pqm.ubuntu.com-20080606135624-1ambbf8pct52xfh8) and a revision _number_ (revno for short, simple integers for mainline revisions, or dotted for merged) is just a convenient shorthand in a particular branch
(06:51:35) LarstiQ: edreamleo: the former is always the same for a particular revision, the latter can change if the mainline changes. (I locally commit 505, someone else can merge that into their 505, then mine will probably be 504.1.1)
(06:52:30) LarstiQ: edreamleo: also practice with `bzr log --show-ids -r -3..-1` and then `bzr diff -r revid:<a revid here>..revid:<and likewise here>`
(06:52:52) LarstiQ: edreamleo: that should give your users/developers a better grasp on the differences I hope.
(06:54:05) edreamleo: LarstiQ: Excellent: practical usage tips will certainly help.
(06:54:19) LarstiQ: edreamleo: and as mathrick said, if people fear their changes have been lost, have a good look at the log output and search for merged revisions. (You can search for a commit log with `bzr log -m <pattern>`)
(06:54:26) LarstiQ: edreamleo: oh! And `bzr missing`
(06:54:49) LarstiQ: edreamleo: bzr missing will compare two branches and tell you which revisions the one has the other hasn't.
(06:56:31) edreamleo: Ok. Enough for now. This is plenty for us newbies to digest. Again, many thanks.
(06:57:11) ***LarstiQ stops :)

EKR

[TL]

Ok. I'll deal with it.
Thanks for the info.

TL