Loading...
Helix SwarmHelix Swarm
Loading...

br01.html

  • //
  • guest/
  • laura_wingerd/
  • perforce/
  • faq/
  • br01.html #2
  • View
  • Commits
  • Open Download .zip Download (9 KB) 
  1. <html>
  2. <head>
  3. <title>The Branching Papers -- Perforce FAQs</title>
  4. <head>
  5. <body bgcolor=#ffffff>
  6. <font size=-2><b><a href="branching.html#br01">[INDEX]</a></b></font>
  7. <p>
  8. <b>
  9. We have a product that will be 
  10. ported and released on HP and on Solaris. Should we branch 
  11. //depot/main into 
  12. //depot/variant-hp and 
  13. //depot/variant-sol? 
  14. And then should we branch off of those for each release?
  15. That seems like a lot of branches to maintain.
  16. </b>
  17. <blockquote>
  18. I suspect your platform-specific porting can be done in client workspaces
  19. mapped to //depot/main.  In this day and age, we expect source code to
  20. be portable enough that a product can be built on any platform from the
  21. same codeline.  However, your actual situation may require a branch, so
  22. read through the following scenarios and decide for yourself.
  23. <p>
  24. Let's say Ruth and Bob are working on fixing generic bugs, Harry is
  25. working on HP, and Susan is working on Solaris. A summary of
  26. their client specs might look like this:
  27. <pre>
  28. 	Client      Root              View		
  29. 	------      ----              ----
  30. 	ruth-bugs   /ruth_fs/bugfix   //depot/main/... //ruth-bugs/...
  31. 	bob-bugs    /bobsdisk/work    //depot/main/... //bob-bugs/....
  32. 	harry-hp    /hp1/harry        //depot/main/... //harry-hp/...
  33. 	susan-sol   /work/solport     //depot/main/... //susan-sol/...
  34. </pre>
  35. Each works in his/her own workspace.  Before they check in changes
  36. from their workspaces, they will have to make sure their changes do
  37. not disrupt the build or cause regressions, because they're all
  38. checking changes into the same codeline, //depot/main.  However,
  39. that should not be a problem for typical porting and bug fixing.
  40. <p>
  41. On the other hand, say Harry and Susan are both working on a complex
  42. internationalization retrofit of a stable product. Their code
  43. changes <i>are</i> likely to cause destabilization, <i>and</i> they need to
  44. check in their untested changes so they can share them with each
  45. other while they're implementing their retrofit. In this case you
  46. would need a separate codeline. Everything would be branched from
  47. the //depot/main codeline into //depot/i18n, for example, using
  48. this branch spec:
  49. <pre>
  50. 	Branch: i18n-retro
  51. 	View:   //depot/main/... //depot/i18n/...
  52. </pre>
  53. and these commands:
  54. <pre>
  55. 	p4 integ -v -b i18n-retro
  56. 	p4 submit
  57. </pre>
  58. (The -v flag causes p4 to do the branching on the server, without
  59. involving the client workspace. Even though the //depot/i18n files still have
  60. to be mapped in your client view, they aren't copied to your workspace
  61. just to branch them in the depot.
  62. This is <i>extremely</i> efficient -- try it!)
  63. <p>
  64. Once the codeline is branched, Harry and Susan would set up their
  65. client views to work in the //depot/i18n codeline.  Now you'd have
  66. clients mapped to two codeline branches:
  67. <pre>
  68. 	Client      Root                View		
  69. 	------      ----                ----
  70. 	ruth-bugs   /ruth_fs/bugfix     //depot/main/... //ruth-bugs/...
  71. 	bob-bugs    /bobsdisk/work      //depot/main/... //bob-bugs/....
  72. 	harry-i18n  /local/i18n         //depot/i18n/... //harry-i18n/...
  73. 	susan-retro /work/retro         //depot/i18n/... //susan-retro/...
  74. </pre>
  75. When Harry checks in a change, Susan can pull his change into her
  76. workspace with <b>p4 sync</b>. However, when Ruth and Bob <b>sync</b>, their
  77. workspaces are unaffected by Harry's I18N-specific changes. 
  78. <p>
  79. As Ruth and Bob fix bugs, however, Harry and Susan are going to
  80. need those fixes. So Harry, as the czar of the //depot/i18n codeline,
  81. periodically pulls the //depot/main changes into //depot/i18n with:
  82. <pre>
  83. 	p4 integ -b i18n-retrofit
  84. 	p4 resolve
  85. 	p4 submit
  86. </pre>
  87. Anytime Harry does this, Susan can then update her I18N workspace with
  88. the bug fixes using <b>p4 sync</b>.
  89. <p>
  90. Eventually Harry and Susan reach their goal of making the I18N
  91. product work.  Now their changes need to be integrated into
  92. //depot/main.  Ruth, as the czar of //depot/main, pulls changes
  93. from //depot/i18n with:
  94. <pre>
  95. 	p4 integ -r -b i18n-retrofit
  96. 	p4 resolve
  97. 	[builds product & runs regression tests]
  98. 	p4 submit
  99. </pre>
  100. So now, the new release is ready. Let's say Ruth is in charge of
  101. the release.  (It's good to have someone in charge.) Since development
  102. is likely to be ongoing in //depot/main, Ruth is going to branch
  103. //depot/main into //depot/r3.  So here's what the branch spec looks
  104. like:
  105. <pre>
  106. 	Branch: r3
  107. 	View:   //depot/main/... //depot/r3/...
  108. </pre>
  109. She creates another client for herself so she can have a //depot/r3
  110. workspace:
  111. <pre>
  112. 	Client: ruthr3
  113. 	Root:	/ruth_fs/r3
  114. 	View:	//depot/r3/... //ruthr3/...
  115. </pre>
  116. She branches the //depot/main codeline into //depot/r3 with these commands:
  117. <pre>
  118. 	p4 integ -v -b r3
  119. 	p4 submit
  120. </pre>
  121. Now you have three codelines:
  122. <pre>
  123.    //depot/i18n           +-------------          
  124.                          / 
  125.    //depot/main  -------+------+----------
  126.                                 \
  127.    //depot/r3                    +----------
  128.  
  129. </pre>
  130. Ruth and her staff build the Release 3 product from the //depot/r3 
  131. codeline on all platforms. They use dedicated release workspaces on
  132. each platform, and set up client specs for each one. E.g.:
  133. <pre>
  134. 	Client      Root                View		
  135. 	------      ----                ----
  136. 	rel3-bsd    /nfs1/rel3/bsd      //depot/r3/... //rel3-bsd/...
  137. 	rel3-hp     /nfs1/rel3/hp       //depot/r3/... //rel3-hp/...
  138. 	rel3-sol    /nfs1/rel3/sol      //depot/r3/... //rel3-sol/...
  139. </pre>
  140. Note that in this example all three of these workspaces are sitting
  141. on the same filesystem, /nfs1. If your source code and build system
  142. are set up in a way that allows you to build product for more than
  143. one platform from the same source code directory tree, you could
  144. even use a single workspace, e.g.,
  145. <pre>
  146. 	Client      Root                View		
  147. 	------      ----                ----
  148. 	rel3        /nfs1/rel3          //depot/r3/... //rel3/...
  149. </pre>
  150. As long as the mount looks like "/nfs1" from every platform, you can
  151. use the same client spec regardless of which platform you're on.
  152. <p>
  153. Now, what happens if a bug is found in the I18N retrofit? Let's say
  154. Release 3 has been out the door for some time, everything hunky-dory,
  155. but now there's this critical I18N bug that has to be fixed for
  156. Release 3 customers.
  157. <p>
  158. With Inter-File Branching, you could fix the bug in any of the
  159. three codelines, and integrate the fix from that codeline into the
  160. other two. However, the <i>best</i> place to fix it is in //depot/r3.
  161. Why?
  162. <p>
  163. <ul>
  164. <p><li>
  165.    If you fix it in //depot/i18n, you have to integrate the fix from
  166.    there into //depot/main, and from there into //depot/r3. That's one
  167.    extra integrate-resolve step.
  168.  
  169. <p><li>
  170.    If you fix it in //depot/main, <i>and</i> there has been subsequent new
  171.    development there, you are applying the fix to code that has evolved
  172.    beyond Release 3. Perforce does facilitate integrating individual
  173.    deltas, but it's extra work for you during the 'resolve' process.
  174. </ul>
  175. <p>
  176. So, Harry is going to fix the I18N bug, and he does it in a new client
  177. workspace he sets up for //depot/r3. His client spec looks something
  178. like:
  179. <pre>
  180. 	Client:	harry-r3
  181. 	Root:	/local/r3
  182. 	View:	//depot/r3/... //harry-r3/...
  183. </pre>
  184. Harry uses these commands to handle the bug fix:
  185. <pre>
  186. 	setenv P4CLIENT harry-r3
  187. 	p4 sync                   # Gets files into his new r3 workspace
  188. 	 ......                   # Does some debugging
  189. 	p4 open foo.c bar.c       # Makes problem files writeable
  190. 	 ......                   # Edits, rebuilds, & tests
  191. 	p4 submit                 # Checks in bug fix to //depot/r3
  192. </pre>
  193. So now Ruth can rebuild the release after doing a <b>p4 sync</b> in her
  194. //depot/r3 workspace. 
  195. <p>
  196. She can also integrate all Release 3 bug fixes into the //depot/main with:
  197. <pre>
  198. 	setenv P4CLIENT ruth-bugs
  199. 	p4 sync
  200. 	p4 integ -r -b r3
  201. 	p4 resolve
  202. 	p4 submit
  203. </pre>
  204. If bug fixes are going into //depot/r3, and new development is going
  205. into //depot/main, what is //depot/i18n good for? Nothing, now. Once
  206. all changes have been integrated from //depot/i18n into //depot/main,
  207. //depot/i18n can be retired. 
  208. <p>
  209. Using a client spec that has a view of //depot/main, you can check to 
  210. see if there are any changes that still need integrating with:
  211. <pre>
  212. 	p4 integ -n -r -b i18n-retro
  213. </pre>
  214. And you can either leave the //depot/i18n files in place in the depot,
  215. or you can tidy up by deleting the files and the branch spec:
  216. <pre>
  217. 	p4 delete //depot/i18n/...
  218. 	p4 submit
  219. 	p4 branch -d i18n-retro
  220. </pre>
  221. (You need to use a client spec that has a view of //depot/i18n to
  222. delete the files.)
  223. <p>
  224. You won't save much space on the server by deleting the files
  225. (because branched files are only virtual copies unless modified), but
  226. by deleting them you are leaving an obvious signpost that they are
  227. no longer needed.
  228. <p>
  229. If you've read this far, I congratulate you. I hope I've come within
  230. at least shouting distance of the answer to your questions...
  231. </blockquote>
  232. <p>
  233. <i>(January 1998)</i>
  234. <p>
  235. <font size=-2><b><a href="branching.html#br01">[INDEX]</a></b></font>
  236. <hr>
  237. <h6>This is file $Id: //guest/laura_wingerd/perforce/faq/br01.html#2 $ in the 
  238. <a href="http://public.perforce.com/public/index.html">
  239. Perforce Public Depot</a></h6>
  240. </body>
  241. </html>
# Change User Description Committed
#2 85 Laura Wingerd Correct typos and add a few clarifications. 26 years ago
#1 83 Laura Wingerd The Branching Papers. 26 years ago