[p4] Branching and ClientSpecs

[Gareth Rees]

At 11:07 +0200 2001-10-19, Andreas Axelsson wrote:
>When we want to make a version or milestone branch, which is the most
>favored way?

I would definitely recommend putting the main codeline under a 
distinguished heading like

   //depot/project/FOO/main/...

(or mainline/... or master/... or whatever).  Then it's natural to 
make the version X codeline by branching the main codeline to

   //depot/project/FOO/version/X/...

Justification:

   1. This naming scheme keeps all the sources for product FOO 
together in the repository.  This is useful for security (you can 
protect the whole project with a single line in the Perforce 
protections), for searching (you can search the project with a single 
find or grep -R), for serving over the web (you only need a single 
webkeeper configuration section), and so on.

   2. Use version/X rather than version-X or version_X to keep the 
top-level project directory simple.  You might want to store all 
manner of things at the top level under project/FOO: for example, 
development branches, product releases, project plans and so on.

>...or should I've thought of this earlier and made it like this...

Indeed.  But it doesn't matter if you didn't think of it earlier; you 
can use Perforce to move the files to where you want them to be. 
Create a branch specification like this:

     //depot/project/FOO/... //depot/project/FOO/main/...
     -//depot/project/FOO/main/... -//depot/project/FOO/main/main/...

Use it to branch all the files in the project so they appear under 
main/...  Then delete the originals.

>Also, what's the preferred way of mapping this to the client. We're using
>devstudio on Windows for most of our development. Should one remove the
>version or head folder in the mapping and have everything go to the same
>root folder on the client, or should one create completely different roots
>and work as if the branch was a completely different set of files?

The issue here is that Microsoft Developer Studio creates workspace 
and project files (.dsw and .dsp) with absolute paths in them.  That 
means that a Developer Studio project that worked as 
D:/project/FOO/main/code/foo.dsw will fail to work when its branched 
to version 1.0 and synced as D:/project/FOO/version/1.0/code/foo.dsw.

There are at least three workarounds for this bug in Developer Studio:

   1. Use drive mappings.  For example, you could arrange to map drive 
P: to the root directory of the codeline you're working on (for 
example, P: would map to D:/project/FOO/main when working on the 
mainline, and to D:/project/FOO/version/1.0 when working on version 
1.0).  Use paths on drive P: in Developer Studio and you should be 
able to use the same workspace in different branches.

Disadvantage: you can't work on two different branches 
simultaneously: you have to keep swapping the drive mapping back and 
forth.  You may often find that you need to be fixing a bug in 
version 1.2 while developing a feature on the main line.

   2. Use different Perforce client specifications for each version 
you're working on.  For example, you might choose D:/foo/ as your 
workspace for project foo.  When working on the mainline you would 
use a client with the mapping

   //depot/project/FOO/main/... //client/foo/...

When working on version 1.0 you would use a client with the mapping

   //depot/project/FOO/version/1.0/... //client/foo/...

Disadvantage: you can't work on two different branches simultaneously 
(see approach 1 above).  You have to be very careful when switching 
work from one branch to another: you have to (1) sync the old branch 
to #none; (2) delete the whole directory hierarchy; (3) switch 
Perforce clients; (4) sync the new branch.  If you miss out any of 
these steps, you may get unwanted intermediate files from the other 
branch, or end up editing the wrong file.

   3. Edit the .dsw and .dsp files in a text editor so that they 
contain only relative pathnames (I know it says ** DO NOT EDIT ** at 
the top of these files, but in fact you can experiment with them in 
the knowledge that you can always p4 revert them if things go wrong). 
Then they will work from any directory, so you can just sync the 
whole of //depot/project/FOO/... and work on the branch or branches 
of your choice.

If you would like to see an example of this kind of approach, take a 
look at Ravenbrook's website; everything under 
<http://www.ravenbrook.com/project/p4dti/> is a copy of the 
corresponding file in our Perforce server.  In particular, the main 
line is <http://www.ravenbrook.com/project/p4dti/master/>, the 
version branches are under 
<http://www.ravenbrook.com/project/p4dti/version/>, there are 
development branches under 
<http://www.ravenbrook.com/project/p4dti/branch/> and so on.  We use 
workaround (3) for the Developer Studio bug; see for example 
<http://www.ravenbrook.com/project/p4dti/master/code/python-teamtrack-interface/teamtrack-5.0.dsp>.