<html>
<STYLE type="text/css">
H1 {border-width: 1; border: solid}
</STYLE>
<title>Scripting Column as of $Date: 2004/08/20 $</title>
<h1><center>Monthly (dev trick) Column for February </center></h1>
<table border=0 width="100%">
<tr><td width="70%">
<p>Greetings!
This continues a series of bulletins, this month focuses
on aspects of how we do software development rapidly.
<td>
<table border=1 width="100%">
<tr><td><i><font color="blue">Tip: integrate often and quickly, but hold off
actually making the branch until you really gotta.</font></i>
</table>
</tr>
</table>
<p>
<blockquote>
<i>This is an excerpt from some internal engineering documents,
so that you can see how we approach this topic internally.</i>
</blockquote>
<hr>
<h2>Today's topic - development branches</h2>
<p>
<p>Sometimes, you have work to checkin and nowhere to put it.
<p>We found that we needed to put out a release that included
Perl/Python, but didn't want to check our Ruby scripts into
"//depot/main/src/..." until release 2.0 went out.
<p>Truth be told, there was no guarantee that release 3.0
was the right release for the Ruby stuff, either. (So any suggestions
to check in the Ruby scripts into a 3.0-specific area don't hold up.)
<em>We needed a place
to check in the work, knowing that it was safe and backed up, but
whence we could retrieve our work to include "when the time was right."
</em>
<hr>
<h3>First step: Deciding to create a development branch</h3>
<p>
Usually, you develop things in your workspace to check into
the <em>main</em> codeline.
A codeline or branch or tree (or whatever you want to call it)
should have one guiding principle, which might be one of the following:
<ol><li>The "main" area that we check new features/files into,
that all new release lines are made from;
<li>The area where "release 1.0" is being finished up;
<li>The area where "release 2.0" is being finished up.
</ol>
For this case, "where to put files that are incompatible with
current work in a codeline/branch/etc" isn't addressed.
Let's add a new branch whose purpose is:
<ol><li>The "development" area where we can check Ruby
scripts until it's okay to move them into "main".
</ol>
This gives us a <em>play-pen</em> to make changes, independently
of the "main" area in which the Python work's getting done.
<p>
<b>Don't bother with development branches for short-term stuff.</b>
It's not worth it, since your workspace is really the best place to
stage work. (Some sites have <em>//depot/sandbox/myusername/...</em>
for you to make impromptu branches for such things. It's pretty useful.)
<h3>Second step: Where to put a development branch?</h3>
<p>It's best to anchor a development branch under "main"
if you can:
<ol><li>That way, the new work isn't tied to a specific release
while under development. If it slips or gets finished early, you can
include it in the most convenient release.
<li>Also, it gives you a consistent place to put 'em.
</ol>
<p>You'll see that we always use <em>named branch specifications</em>
for this work. (It makes the integration work consistent and
avoids typos.) An example is below:
<blockquote>
<pre>
Branch: rubydev2002
Owner: eddie
Description:
Created by eddie.
Options: unlocked direct
View:
<font color="green">//depot/main/src/... //depot/devbranches/ruby2002/src/...</font>
-//depot/main/policy.html //depot/devbranches/ruby2002/policy.html
-//depot/main/include/version.h //depot/devbranches/ruby2002/include/version.h
</pre>
</blockquote>
<p>
Note the <font color="green">green</font> text. It establishes
that a new tree, <em>//depot/devbranches/ruby2002</em>, will pull
its initial revisions from <em>//depot/main</em> when we run:
<pre>
p4 integrate -b rubydev2002 //...@2002/01/30
p4 submit
</pre>
<p>So we'll end up with a new tree to work in, populated with
a copy of <em>//depot/main</em> from the end of January. (Jan 30,
and since we didn't specify time-of-day, it'll be the first second of the day.)
<h3>Third step: Working in a development branch</h3>
<p>It's just a place to check in files - have at it.
<p>The one detail is that you want to respect the branch's "goal."
If it's a Ruby development branch, don't check in Perl bug fixes there.
<h3>Fourth step: Bringing your work back into normal development</h3>
<p>
At some point - perhaps several points along the way - you'll want to
pull your work back to the parent codeline/branch.
The reverse-integration adds a "-r" to the commands,
but otherwise is fairly easy:
<pre>
p4 integrate <font color="red">-r</font> -b rubydev2002 //...@2002/01/30
<font color="red">p4 resolve</font>
</pre>
<p>
The "resolve" step is straight-forward, but requires a bit
of attention. (Don't use "accept theirs" to get the virtual-copy
behavior - for back-integrations, it's usually a poor choice.)
<p>
Then, after many regressions and fixing things in your workspace...
<pre>
p4 submit
</pre>
<h3>Last step: Obsoleting the branch</h3>
<p>Once you've reverse-integrated everything, you need to stop using
the development branch. ("main" lasts forever. Development branches
shouldn't, so that you can always start with a fresh and blessed copy of
the code for new work in a new branch. It's easier to maintain.)
<p>Some people make the development branch invisible using "p4
protect" ; others delete the files in the development branch.
The first one, with 'p4 protect', is the preferred approach.
(It's best to avoid the second approach - you might accidently integrate the delete operations.)
<h3>Comments</h3>
<p>A development branch is helpful for many situations - branching the
entire tree, a small subtree, or just the Makefiles or header files.
In the partial-tree case, you might map the rest of the production "main" into your workspace, so that - to you - it looks like a normal source area but meets your specialized needs.
<hr>
<i><small>$Id: //guest/jeff_bowles/scripts/0228devbranch.html#2 $</small>
<br>© 2004 Perforce Corporation, Inc.</small></i>
</html>
| # | Change | User | Description | Committed | |
|---|---|---|---|---|---|
| #2 | 4421 | Jeff Bowles | Adding the beginnings of some "example scripts" columns. | ||
| #1 | 4420 | Jeff Bowles |
adding the beginnings of example "columns" for scripting examples. |