files/0228devbranch.html

0228devbranch.html 

  1. <html>
  2. <STYLE type="text/css">
  3.    H1 {border-width: 1; border: solid}
  4.  </STYLE>
  5. <title>Scripting Column as of $Date: 2004/08/20 $</title>
  6. <h1><center>Monthly (dev trick) Column for February </center></h1>
  7. <table border=0 width="100%">
  8. <tr><td width="70%">
  9. <p>Greetings!
  10. This continues a series of bulletins, this month focuses
  11. on aspects of how we do software development rapidly.
  12. <td>
  13. 	<table border=1 width="100%">
  14. 	<tr><td><i><font color="blue">Tip: integrate often and quickly, but hold off
  15. 	actually making the branch until you really gotta.</font></i>
  16. 	</table>
  17. </tr>
  18. </table>
  19. <p>
  20. <blockquote>
  21. <i>This is an excerpt from some internal engineering documents,
  22. so that you can see how we approach this topic internally.</i>
  23. </blockquote>
  24. <hr>
  25. <h2>Today's topic - development branches</h2>
  26. <p>
  27. <p>Sometimes, you have work to checkin and nowhere to put it.
  28. <p>We found that we needed to put out a release that included
  29. Perl/Python, but didn't want to check our Ruby scripts into
  30. &quot;//depot/main/src/...&quot; until release 2.0 went out.
  31. <p>Truth be told, there was no guarantee that release 3.0
  32. was the right release for the Ruby stuff, either. (So any suggestions
  33. to check in the Ruby scripts into a 3.0-specific area don't hold up.)
  34. <em>We needed a place
  35. to check in the work, knowing that it was safe and backed up, but
  36. whence we could retrieve our work to include &quot;when the time was right.&quot;
  37. </em>
  38. <hr>
  39. <h3>First step: Deciding to create a development branch</h3>
  40. <p>
  41. Usually, you develop things in your workspace to check into
  42. the <em>main</em> codeline.
  43. A codeline or branch or tree (or whatever you want to call it)
  44. should have one guiding principle, which might be one of the following:
  45. <ol><li>The &quot;main&quot; area that we check new features/files into,
  46.         that all new release lines are made from;
  47.     <li>The area where &quot;release 1.0&quot; is being finished up;
  48.     <li>The area where &quot;release 2.0&quot; is being finished up.
  49. </ol>
  50. For this case, &quot;where to put files that are incompatible with
  51. current work in a codeline/branch/etc&quot; isn't addressed.
  52. Let's add a new branch whose purpose is:
  53. <ol><li>The &quot;development&quot; area where we can check Ruby
  54. scripts until it's okay to move them into &quot;main&quot;.
  55. </ol>
  56. This gives us a <em>play-pen</em> to make changes, independently
  57. of the &quot;main&quot; area in which the Python work's getting done.
  58. <p>
  59. <b>Don't bother with development branches for short-term stuff.</b>
  60. It's not worth it, since your workspace is really the best place to
  61. stage work. (Some sites have <em>//depot/sandbox/myusername/...</em>
  62. for you to make impromptu branches for such things. It's pretty useful.)
  63. <h3>Second step: Where to put a development branch?</h3>
  64. <p>It's best to anchor a development branch under &quot;main&quot;
  65. if you can:
  66. <ol><li>That way, the new work isn't tied to a specific release
  67. while under development. If it slips or gets finished early, you can
  68. include it in the most convenient release.
  69. <li>Also, it gives you a consistent place to put 'em.
  70. </ol>
  71. <p>You'll see that we always use <em>named branch specifications</em>
  72. for this work. (It makes the integration work consistent and
  73. avoids typos.) An example is below:
  74. <blockquote>
  75. <pre>
  76. Branch:	rubydev2002
  77.  
  78. Owner:	eddie
  79.  
  80. Description:
  81. 	Created by eddie.
  82.  
  83. Options:	unlocked direct
  84.  
  85. View:
  86. 	<font color="green">//depot/main/src/... //depot/devbranches/ruby2002/src/...</font>
  87. 	-//depot/main/policy.html //depot/devbranches/ruby2002/policy.html
  88. 	-//depot/main/include/version.h //depot/devbranches/ruby2002/include/version.h
  89. </pre>
  90. </blockquote>
  91. <p>
  92. Note the <font color="green">green</font> text. It establishes
  93. that a new tree, <em>//depot/devbranches/ruby2002</em>, will pull
  94. its initial revisions from <em>//depot/main</em> when we run:
  95. <pre>
  96.    p4  integrate  -b  rubydev2002  //...@2002/01/30
  97.    p4  submit
  98. </pre>
  99. <p>So we'll end up with a new tree to work in, populated with
  100. a copy of <em>//depot/main</em> from the end of January. (Jan 30,
  101. and since we didn't specify time-of-day, it'll be the first second of the day.)
  102. <h3>Third step: Working in a development branch</h3>
  103. <p>It's just a place to check in files - have at it.
  104. <p>The one detail is that you want to respect the branch's &quot;goal.&quot;
  105. If it's a Ruby development branch, don't check in Perl bug fixes there.
  106. <h3>Fourth step: Bringing your work back into normal development</h3>
  107. <p>
  108. At some point - perhaps several points along the way - you'll want to
  109. pull your work back to the parent codeline/branch.
  110. The reverse-integration adds a &quot;-r&quot; to the commands,
  111. but otherwise is fairly easy:
  112. <pre>
  113.    p4  integrate  <font color="red">-r</font>  -b  rubydev2002  //...@2002/01/30
  114.    <font color="red">p4  resolve</font>
  115. </pre>
  116. <p>
  117. The &quot;resolve&quot; step is straight-forward, but requires a bit
  118. of attention. (Don't use &quot;accept theirs&quot; to get the virtual-copy
  119. behavior - for back-integrations, it's usually a poor choice.)
  120. <p>
  121. Then, after many regressions and fixing things in your workspace...
  122. <pre>
  123.    p4  submit
  124. </pre>
  125. <h3>Last step: Obsoleting the branch</h3>
  126. <p>Once you've reverse-integrated everything, you need to stop using
  127. the development branch. (&quot;main&quot; lasts forever. Development branches
  128. shouldn't, so that you can always start with a fresh and blessed copy of
  129. the code for new work in a new branch. It's easier to maintain.)
  130. <p>Some people make the development branch invisible using &quot;p4
  131. protect&quot; ; others delete the files in the development branch.
  132. The first one, with 'p4 protect', is the preferred approach.
  133. (It's best to avoid the second approach - you might accidently integrate the delete operations.)
  134. <h3>Comments</h3>
  135. <p>A development branch is helpful for many situations - branching the
  136. entire tree, a small subtree, or just the Makefiles or header files.
  137. In the partial-tree case, you might map the rest of the production &quot;main&quot; into your workspace, so that - to you - it looks like a normal source area but meets your specialized needs.
  138.  
  139. <hr>
  140. <i><small>$Id: //guest/jeff_bowles/scripts/0228devbranch.html#2 $</small>
  141. <br>&copy; 2004 Perforce Corporation, Inc.</small></i>
  142. </html>
# Change User Description Committed
#2 4421 Jeff Bowles Adding the beginnings of some "example scripts" columns. 21 years ago
#1 4420 Jeff Bowles adding the beginnings of example "columns" for
    scripting examples. 		21 years ago