Here's some advice about managing branches, and some advice 
about recovering from the not quite right way of managing branches
(from the arch-users mailing list).


To: geisler@ece.nwu.edu
CC: arch-users@regexps.com
In-reply-to: <20020208234810.A31A159D7@nasser.ece.nwu.edu>
	(geisler@ece.nwu.edu)
Subject: Re: help understanding merging better
References:  <20020208234810.A31A159D7@nasser.ece.nwu.edu>
-text follows this line--


      I'm trying to figure out exactly how to best merge my private
      line with the public one

This is kind of an interesting question and since its on the list,
I'm going to take the liberty of giving a really long answer.

There are really three parts to the answer.  Part 1 is "The Best Way
to Organize Branches" Part 2 is "What You've Actually Done" based on
your description and your log messages and Part 3 is "How to Deal With
What You've Got".


		  The Best Way to Organize Branches
		  =================================


Ideally, what you *should* have is a topology as illustrated below,
where arrows like "A -> B" mean "B is a branch of A".  (I understand
you to be saying that you want to have two branches, in two archives,
with one archive public and the other private.)


			   |   geisler@ece.nwu-edu--public
			   |
		devo------------------->devo
		|	   |		|
		|   	   |------------|-------------------
		V   	   |   		V
		lord	   |		geisler
			   |
   lord@regexps.com--2002  |
 			   |   geisler@ece.nwu-edu--private


With that topology, I merge back and forth between my "devo" and
"lord", using `star-merge'.  You merge back and forth between your
"devo" and "geisler" using `star-merge'.  We both merge back and forth
between the two "devo" branches using `star-merge'.  And it all works
beautifully :-).

It gets a little bit more complicated if you want to keep changes in
your devo branch that I don't want or vice versa -- I'll leave a full
explanation of dealing with that for another context.

If you were working on some large complex change -- something that
wouldn't show up on either "devo" branch until we'd tossed it around a
bit -- then it would best to make an additional branch from your
"devo" just for that change.

Ideally, each patch set that you want me to look at should be for
a single purpose -- that makes them easier to review.  But when it
comes to merging, if you have 10 patch sets in a row that I'll take,
there's no reason not to merge them all at once.  The upshot of this
is that it might be more convenient to make the one-at-a-time patch
sets in your geisler branch, have me review those, then batch them up
in a merge with your devo, which I can then merge with my devo.  But
to review them, your geisler branch should be public and you should
have a browser.  In other words, you might want:



			   |   geisler@ece.nwu-edu--public
			   |	            .
		devo------------------->devo.-->geisler
		|	   |		    .
		|   	   |----------------.---------------
		V   	   |   		    .
		lord	   |		    .
			   |                .
   lord@regexps.com--2002  |                V
 			   |   geisler@ece.nwu-edu--private


where "A .....> B" means "archive A is a mirror of archive B" which is
similar to what I've got with the regexps.com archive and the archive
I have at home (connected over a 56Kb/s, transiently connected modem).

But on to the actual situation:






		      What You've Actually Done
		      =========================



I think you actually have:



			   |   geisler@ece.nwu-edu--public
			   |
       	       	devo------------------->geisler
		|      	\  |
		|      	 | |--------------------------------
		V      	 | |
		lord     +------------->geisler
			   |
   lord@regexps.com--2002  |
 			   |   geisler@ece.nwu-edu--src



(It's the arrow from my devo to your private geisler that I'm unsure
of -- perhaps it should be an arrow from your public geisler -- but
that doesn't make much difference.)

I checked out a copy of arch--geisler--1.0--patch-6 from your public
archive.  Looking at `merge-points' output, it seems that you created
the branch at my `arch--devo--1.0--patch-36', then at your patch-1,
updated to my `patch-37'.  Then in your patches 2-6, used `replay' to
apply a selection of patches from your `--src' archive.   You now have
something like:


	lord's		geisler's public	geisler's src (private)
	devo		geisler			geisler
	===============================================================


	patch-27 -----------------------------> base-0
	...					...		[A]
	patch-36 -----> base-0
	patch-37 --m--> patch-1
	...		patch-2 <--r.e.-------- patch-2
			patch-3 <--r.e.-------- patch-3
			patch-4 <--r.e.-------- patch-4
				   		.... 		[B]
			patch-5 <--r.e.-------- patch-13
			patch-6 <--r.e.-------- patch-14
						....		[C]


		key:
			X --------> Y	Y is a branch from X

			X ---m----> Y	Everything up to X, merged
					into Y

			X --r.e.--> Y	patch set X applied to Y by 
					`replay --exact'


Somewhere at points [A], [B], and [C], you've also merged everything
from my devo into your private geisler branch.  Now you want to make
sure that your public geisler contains everything from your private
geisler, and be able to easily keep them in sync in the future.

You are right -- `reconcile' isn't quite designed for the situation
you have.



		   How to Deal With What You've Got
		   ================================

There are many solutions and which one is best depends on your goals.

One option is to continue to use `replay --exact' to move patches from
your private geisler branches to the public branches.  That's a bit
tedious, but it allows you to keep patches on your private geisler
that don't appear in the public geisler (normally you'd want a
separate branch for permanently private patches).

Another option is to trash your current public archive and replace it
with a mirror of your private archive.  That shouldn't be a problem
since, at this point, nobody has any branches from your current public
archive or has merged in patches from your current public archive.
(If people already had used your public archive, then you could start
an archive with a new name and make that the mirror of your private
archive.)

I'll assume though, that you'd rather keep your current archives and
that you want to be using `star-merge' rather than `replay --exact' in
the future.  In other words, that you want to get from the situation
you have to a situation that works like the "ideal" branch topology at
the top of this message.  That's doable -- at least in theory: you'll
be the first to try it in practice.

First, upgrade your installed version of arch to 1.0pre7.  Sorry, I
did have to add about 5 lines of code to deal with this situation.

Next, bring both of your geisler branches up-to-date with my devo
branch.  You seem to already know how to do that.  (If they're both
branches from my devo, `update' and `star-merge' should both work.)
If you have any more patches in your private geisler that you want to
add to the public geisler as "clean patch sets (i.e., not all lumped
together as one big patch), use `replay --exact' to do that now, too.


Now, for each package, get three project trees:


	A: your private geisler
	B: your public geisler
	C: the common ancestor of A and B from my devo


Next:

	% larch mkpatch C A c-a-patch

	% larch dopatch --forward a-c-patch B


	# make the log message, then:
	# 

	% larch commit B


	% larch mkpatch C B c-b-patch

	% larch dopatch --forward c-b-patch A

	# make the log message, then:
	# 

	% larch commit A


The new "--forward" option to "dopatch" just passes the option
"--forward" to GNU patch.

Thereafter, you should be able to use `star-merge' as described in the
first part of this message.

Finally, looking at your log messages, I see that you are writing log
messages for merges by hand.  If the merged-from and merged-to
branches are both visible to whomever needs to review the patches, you
should instead use:

	% larch log-for-merge

to generate the body of the log message.  That standardizes the
cross-referencing in automatically generated ChangeLog files for your
branches.


# tag: Tom Lord Sat Feb  9 07:58:18 2002 (examples/README.025.branching-advice)
#
