www/merge-tracking/requirements.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <style type="text/css"> /* <![CDATA[ */
   6   @import "../branding/css/tigris.css";
   7   @import "../branding/css/inst.css";
   8   /* ]]> */</style>
   9 <link rel="stylesheet" type="text/css" media="print"
  10   href="../branding/css/print.css"/>
  11 <script type="text/javascript" src="../branding/scripts/tigris.js"></script>
  12 <title>Merge Tracking Requirements and Use Cases</title>
  13 </head>
  14
  15 <body>
  16 <div class="h2">
  17 <h2>Merge Tracking Requirements and Use Cases</h2>
  18
  19 <p>This document details Subversion's <a href="index.html">merge
  20 tracking</a> requirements and their supporting use cases, the majority
  21 of which are driven by Subversion's <a
  22 href="../user-classifications.html#developer">Developer</a> and <a
  23 href="../user-classifications.html#merge-meister">Merge Meister</a>
  24 users.  A few outliers are driven by <a
  25 href="../user-classifications.html#program">SCM automation</a>.</p>
  26
  27 <div id="requirements">
  28
  29 <div class="h3" id="summary">
  30 <h3>Summary</h3>
  31
  32 <ul>
  33   <li>
  34     <a href="#merging">Merging</a>
  35     <ul>
  36       <li><a href="#repeated-merge">Repeated Merge</a></li>
  37       <li><a href="#cherry-picking">Cherry Picking</a></li>
  38       <li><a href="#rename-tracking">Handle Renames</a></li>
  39       <li><a href="#manual-merge">Record Manual Merge</a></li>
  40       <li><a href="#rollback-merge">Rollback Merge</a></li>
  41       <li><a href="#revision-blocking">Block/Unblock Changeset</a></li>
  42       <li><a href="#properties">Properties</a></li>
  43       <li><a href="#merge-previews">Preview</a></li>
  44       <li><a href="#automated-merge">SCM Automation</a></li>
  45       <li><a href="#distributable-resolution">Distribution of Conflict
  46       Resolution</a></li>
  47     </ul>
  48   </li>
  49
  50   <li>
  51     <a href="#auditing">Auditing</a>
  52     <ul>
  53       <li><a href="#change-set-availability">Changeset Merge
  54       Availability</a></li>
  55       <li><a href="#find-change-set">Find Changeset</a></li>
  56       <li><a href="#commutative-author-and-rev">Commutative Author and
  57       Revision Reporting for Merged Changesets</a></li>
  58       <!-- ### Need to explicitly call out renames? -->
  59     </ul>
  60   </li>
  61
  62   <li>
  63     <a href="#misc">Miscellaneous</a>
  64     <ul>
  65       <li>Consistent UI</li>
  66       <li><a href="#dump-load">Allow Dump/Load</a></li>
  67       <li><a href="#compatibility">Compatibility with older Subversion
  68             clients</a></li>
  69       <li><a href="#versioning">Versioning</a></li>
  70       <li><a href="#authz">Authorization</a></li>
  71     </ul>
  72   </li>
  73 </ul>
  74
  75 </div>  <!-- summary -->
  76
  77
  78 <div class="h3" id="merging">
  79 <h3>Merging</h3>
  80
  81 <div class="h4" id="repeated-merge">
  82 <h4>Repeated Merge</h4>
  83
  84 <p>Track which changesets have been applied where, so users can
  85 repeatedly merge branch A to branch B without having to remember the
  86 last range of revisions ported.  This would also track
  87 changeset <a href="#cherry-picking">cherry picking</a> done by users,
  88 so we don't accidentally re-merge changesets that are already applied.
  89 This is the problem that <a href="http://svk.elixus.org/">svk</a>
  90 and <a href="http://www.gnu.org/software/gnu-arch/">arch</a> claim to
  91 have already solved, what they're calling <em>star-merge</em>
  92 (although svk does not support cherry-picking in a sense compatible
  93 with repeated merge).</p>
  94
  95 </div>  <!-- repeated-merge -->
  96
  97 <div class="h4" id="cherry-picking">
  98 <h4>Cherry Picking</h4>
  99
 100 <p>Merge of one or more individual changesets, or changes from a
 101 changeset (e.g. to two out of three files), from branch A into branch
 102 B (as opposed to merge of all previously unmerged changes).</p>
 103
 104 <p>This sometimes involves manual adjustment of a change merged from
 105 branch A into a WC for branch B before the change is committed to the
 106 repository, or <a href="#manual-merge">manual application</a> of a
 107 changeset from branch A to the WC (e.g. not using <code>svn
 108 merge</code>).  Regardless of the merge method used, Subversion must
 109 provide a way to <a href="#manual-merge">indicate that the change(s)
 110 have been merged</a> into branch B.</p>
 111
 112 <p>Additionally, it's important to be able to cherry pick changes in
 113 multiple different directions.  For example, if you create a release
 114 branch B by copying the trunk you should be able to both forward port
 115 changes made on B into trunk and backport changes made on trunk into B
 116 without confusing the merge tracking algorithm.  (This problem is
 117 harder when you choose to cherry-pick a change from one branch to
 118 another that you had previously cherry-picked in the other direction;
 119 Subversion may not support this perfectly.)</p>
 120
 121 <p>Use may be predicated on information from the <em>Show Changesets
 122 Available for Merge</em> feature (<a href="#auditing">Auditing</a>
 123 section).</p>
 124
 125 </div>  <!-- cherry picking -->
 126
 127 <div class="h4" id="rename-tracking">
 128 <h4>Track Renames in Merge</h4>
 129
 130 <p><code>svn merge</code> needs to handle renames better.  This
 131 requires <a
 132 href="http://subversion.tigris.org/issues/show_bug.cgi?id=898">true
 133 rename support</a>.</p>
 134
 135 <p>Edit foo.c on branch A.  Rename foo.c to bar.c on branch B.</p>
 136
 137 <ol>
 138   <li>Try merging the branch A edit into a working copy of branchB:
 139   <code>svn merge</code> will skip the file, because it can't find
 140   it.</li>
 141
 142   <li>Conversely, try merging branch B rename to branch A: <code>svn
 143   merge</code> will delete the 'newer' version of foo.c and add bar.c,
 144   which has the older text.</li>
 145 </ol>
 146
 147 <p>Problem #2 stems from the fact that we don't have <a
 148 href="http://subversion.tigris.org/issues/show_bug.cgi?id=898">true
 149 renames</a>, just copies (with history) and deletes.  That's not
 150 fixable without a FS schema change, and (probably) a libsvn_wc
 151 rewrite.</p>
 152
 153 <p>It's not clear what it would take to solve problem #1.  See <a
 154 href="http://svn.haxx.se/dev/archive-2004-07/0084.shtml">the
 155 discussion</a> about our rename woes, and the relationship to merge
 156 tracking.</p>
 157
 158 </div>  <!-- rename-tracking -->
 159
 160 <div class="h4" id="manual-merge">
 161 <h4>Record Manual Merge</h4>
 162
 163 <p>Allow changesets to be marked as merged, effectively a way to
 164 manipulate the merge memory on target for a given merge source.  This
 165 is related to -- but not semantically equivalent to -- the <a
 166 href="#revision-blocking">revision blocking</a> concept.</p>
 167
 168 <p>Fundamentally, the use case is to support merge tracking of a
 169 changeset which is sufficiently different when ported to a different
 170 branch that use of <code>svn merge</code> is no longer appropriate.
 171 Examples scenarios include:</p>
 172
 173 <ul>
 174   <li>The actual change you want to apply to branch has no overlap
 175   with its incarnation on the source branch, yet is conceptually
 176   equivalent.</li>
 177
 178   <li>Only a subset of a changeset warrants application.</li>
 179
 180   <li>The branch content has drifted far enough apart to make
 181   automatic merging impossible (e.g. excessive merge conflicts are
 182   generated).</li>
 183 </ul>
 184
 185 <p>Use may be predicated on information from the <em>Show Changesets
 186 Available for Merge</em> feature (<a href="#auditing">Auditing</a>
 187 section).  Use supports <a href="#cherry-picking"><i>Cherry
 188 Picking</i></a>.</p>
 189
 190 </div>  <!-- manual-merge -->
 191
 192 <div class="h4" id="rollback-merge">
 193 <h4>Rollback Merge</h4>
 194
 195 <p>Undo a merge and/or associated tracking meta data.  Necessary for
 196 both <a href="#repeated-merge">automated</a> and <a
 197 href="#manual-merge">manual</a> merges.</p>
 198
 199 <p>Use may be predicated on information from the <em>Show Changesets
 200 Available for Merge</em> and <em>Show Changesets Already Merged</em>
 201 features (<a href="#auditing">Auditing</a> section).</p>
 202
 203 </div>  <!-- rollback-merge -->
 204
 205 <div class="h4" id="revision-blocking">
 206 <h4>Block/Unblock Changeset</h4>
 207
 208 <p>Protect revisions of a source which should never be merged from
 209 accidental merging.</p>
 210
 211 <p>This includes both blocking merging of specific revisions into a
 212 path, and blocking merging of a specific revision to any path.</p>
 213
 214 </div>  <!-- revision-blocking -->
 215
 216 <div class="h4" id="properties">
 217 <h4>Properties</h4>
 218
 219 <p>Changes to arbitrary properties set on a versioned resource should
 220 be mergable exactly as entries within a directory (e.g. add, deleted,
 221 etc.), or content in a file (see <a href="#repeated-merge">repeated
 222 merge</a>).</p>
 223
 224 <p>Subversion's <em>revision properties</em> (sometimes referred to as
 225 <em>revprops</em>) need not be handled.</p>
 226
 227 </div>  <!-- properties -->
 228
 229 <div class="h4" id="merge-previews">
 230 <h4>Merge Previews</h4>
 231
 232 <p>Merge previews are dry runs that show conflicts and "non-trivial,
 233 non-conflicting" (NTNC) changes in advance.  These previews should be
 234 exportable and parseable.  (From the <a href="summit.html#merge-previews"
 235 >distributable resolution item</a> in the summit summary.)</p>
 236
 237 </div>  <!-- merge-previews -->
 238
 239 <div class="h4" id="automated-merge">
 240 <h4>SCM Automated Merge</h4>
 241
 242 <p>The ability to automate merges (e.g. from a stable branch to a
 243 development branch), including interfaces for resolving conflicts and
 244 handling other errors, is important.  <a
 245 href="../user-classifications.html#merge-meister">Merge Meisters</a>
 246 who do multi-thousand file merges stress this.</p>
 247
 248 </div>  <!-- automated-merge -->
 249
 250 <div class="h4" id="distributable-resolution">
 251 <h4>Distributability of Merge Resolution</h4>
 252
 253 <p>The mechanism for resolving conflicts in a merge should be
 254 distributable across N developers.  Meeting this requirement might
 255 mean a departure for Subversion, since it implies that merge results
 256 are not just stored in one working copy, but are somehow available on
 257 the server side.  (From the <a href="summit.html#distributable-resolution"
 258 >distributable resolution item</a> in the summit summary.)</p>
 259
 260 </div>  <!-- distributable-resolution -->
 261
 262 </div>  <!-- merging -->
 263
 264
 265 <div class="h3" id="auditing">
 266 <h3>Auditing</h3>
 267
 268 <p>Merge tracking must be audit-friendly, supporting some basic forms
 269 of reporting which allow for discovery of at least the following types
 270 of information.</p>
 271
 272 <p>Additionally, merge info should be transitive.  Often we merge a
 273 bunch of changes to a backport branch, tweak them there, then later
 274 merge the branch into a release line.  Later queries of the release
 275 line should show that the original revisions are present, and queries
 276 of the original revisions should show that they went to the release
 277 line as well as the backport branch.</p>
 278
 279 <div class="h4" id="change-set-availability">
 280 <h4>Changeset Merge Availability</h4>
 281
 282 <dl>
 283   <dt>Show Changesets Available for Merge</dt>
 284   <dd>Support query of any path (file, directory, or symlink) to find
 285   out what changes (revisions) for a merge source haven't been merged
 286   under it.  For files, "under" just means "into".</dd>
 287
 288   <dt>Show Changesets Already Merged</dt>
 289   <dd>Support query any path (file, directory, or symlink) to find out
 290   what changes (revisions) have been merged under it.  For files,
 291   "under" just means "into".</dd>
 292
 293   <dt>Show Changesets Blocked from Merging</dt>
 294   <dd>If you've <a href="#revision-blocking">blocked</a> some set
 295   of revisions from being merged from branch B into some destination
 296   (e.g. trunk), you should be able to discover which revisions have
 297   been blocked.</dd>
 298 </dl>
 299
 300 </div>  <!-- change-set-availability -->
 301
 302 <div class="h4" id="find-change-set">
 303 <h4>Find Changeset</h4>
 304
 305 <dl>
 306   <dt><em>Merged From</em> info for Changeset and/or Path</dt>
 307   <dd>If you merged rN from branch A into branch B in rM, it should be
 308   possible to query rM -- or branch B at or after rM, but before it's
 309   been moved or deleted -- to ask what sources it has been merged
 310   from, and the answer set should contain A at rN.</dd>
 311
 312   <dt><em>Merged To</em> info for Changeset and/or Path</dt>
 313   <dd>If you merge rN from branch A into branch B in rM, it should be
 314   possible to query rN -- or branch A at or after rN, but before it's
 315   been moved or deleted -- to ask what destinations it has been merged
 316   to, and the answer set should contain B at rM.</dd>
 317
 318   <dt>Find Paths containing Specific Incarnation of Versioned Resource</dt>
 319   <dd>It should be easy to discover all the paths at which a
 320   particular node revision (i.e., unique versioned file entity)
 321   exists, especially in a given revision.  In other words, this is the
 322   "what branches does this exact version of this file exist in"
 323   problem, often requested by so-called enterprise-level users.</dd>
 324 </dl>
 325
 326 <p>Blue sky, we may want to enhance the reporting capabilities to
 327 allow retrieval of a log of changes to merge tracking information.
 328 This log should list both when the merges were applied, and when the
 329 merge meta data was updated.</p>
 330
 331 </div>  <!-- find-changeset -->
 332
 333 <div class="h4" id="commutative-author-and-rev">
 334 <h4>Commutative Author and Revision Reporting for Merged Changesets</h4>
 335
 336 <p>The ability to report either/both the actual committer and revision
 337 number of a changeset, and/or the original author and revision
 338 number.  This applies to any operations which report an author,
 339 including:</p>
 340
 341 <ul>
 342   <li><code>blame</code></li>
 343   <li><code>log</code></li>
 344 </ul>
 345
 346 <p>For example:</p>
 347
 348 <ul>
 349   <li>If you merge rN into a branch B, and rN was committed by author
 350   A, then <code>svn blame</code> should provide the ability to show
 351   the changed lines in B as last touched by A, even if the merge was
 352   committed by you and you are not A.  This must also work when
 353   merging a range of revisions with different authors.</li>
 354
 355   <li>If you merge rN into a branch B, and rN was committed by author
 356   A, then <code>svn log -rN</code> should show both the original
 357   author A, <em>and</em> the author who merged the change.</li>
 358 </ul>
 359
 360 <p>The UI and API for toggling this behavior should be consistent
 361 across operations.</p>
 362
 363 </div>  <!-- commutative-author-and-rev -->
 364
 365 </div>  <!-- auditing -->
 366
 367
 368 <div class="h3" id="misc">
 369 <h3>Miscellaneous</h3>
 370
 371 <div class="h4" id="dump-load">
 372 <h4>Allow for Dump/Load</h4>
 373
 374 <p>Whatever solution is chosen must play well with <code>svnadmin
 375 dump</code> and <code>svnadmin load</code>.  For example, the metadata
 376 used to store merge tracking history must not be stored in terms of
 377 some filesystem backend implementation detail (e.g.
 378 "node-revision-ids") unless, perhaps, those IDs are present for all
 379 items in the dump as a sort of "soft data" (which would allow them to
 380 be used for "translating" the merge tracking data at load time, where
 381 those IDs would be otherwise irrelevant).  See <a
 382 href="http://subversion.tigris.org/issues/show_bug.cgi?id=1525">issue
 383 1525</a> about user-visible entity IDs.</p>
 384
 385 </div>  <!-- dump-load -->
 386
 387 <div class="h4" id="common-case-ease">
 388 <h4>User Interface Ease in Common Cases</h4>
 389
 390 <p>(This was one of the points made at the <a
 391 href="http://svn.collab.net/repos/svn/trunk/notes/EuroOSCON-2005-vc-bof.txt"
 392 >EuroOSCON 2005 Version Control BOF session</a>.)</p>
 393
 394 <p>The interface for common-case merges should be easy.  Currently it
 395 is not.  For example, a very common case is merging all previously
 396 unmerged changes from trunk to branch (more formally, from a source
 397 line to a descendant destination line).  Today, one must type
 398 <code>svn&nbsp;merge&nbsp;-rX:Y&nbsp;URL&nbsp;WC</code>.  But why
 399 can't the dest just remember what has been merged from that src before
 400 and do the right thing?  Then one could type
 401 <code>svn&nbsp;merge&nbsp;SRC&nbsp;DST</code>.  Or better yet,
 402 branches could remember where they come from, and one could just type
 403 <code>svn&nbsp;merge&nbsp;SRC</code>, or
 404 <code>svn&nbsp;merge&nbsp;DST</code>, depending on whether one wants a
 405 push or pull interface.  (It was pointed out that SVK does remember
 406 these things; if someone familiar with the SVK interface wants to put
 407 an example transcript here, that would be great.)</p>
 408
 409 <p>Here is the svk command transcript:
 410 </p>
 411 <blockquote>
 412 <p>
 413 A branch creation by:
 414 <code>svk copy //project/trunk //project/branch-B</code>
 415 (or mirroring an existing subversion repository containing such branch)
 416 </p>
 417
 418 <p>
 419 To merge from trunk to branch-B:
 420 <code>svk smerge //project/trunk //project/branch-B</code>, or
 421 <code>svk smerge --to //project/branch-B</code>, or
 422 <code>svk pull //project/branch-B</code>
 423 </p>
 424 <p>
 425 To merge from branch-B back to trunk:
 426 <code>svk smerge //project/trunk //project/branch-B</code>, or
 427 <code>svk smerge --from //project/branch-B</code>, or
 428 <code>svk push //project/branch-B</code>
 429 </p>
 430
 431 <p>
 432 There is also a <code>-I</code> flag in smerge to merge changes
 433 revision-by-revision.  Push is by default with the option, and
 434 pull is not.
 435 </p>
 436
 437 </blockquote>
 438
 439 <p>Another common case is porting a single change from one line to
 440 another.  This currently requires <code>-r&lt;X-1&gt;:X</code> syntax,
 441 but Subversion 1.4 will include the <code>-c</code> option (introduced
 442 in <a href="http://svn.collab.net/viewvc/svn?rev=17054&amp;view=rev"
 443 >r17054</a>), so users will no longer need to perform this menial
 444 arithmetic.  However, Subversion 1.4 will still require the URL of the
 445 merge source to be specified; a merge tracking solution that eases
 446 common cases would obviate the need for the user to supply the URL
 447 when a single change is ported from a branch's ancestor line.</p>
 448
 449 <p>svk merge also supports <code>-c N</code> flag which is
 450 <code>-rN-1:N</code>.</p>
 451
 452 </div>  <!-- common-case-ease -->
 453
 454 <div class="h4" id="compatibility">
 455 <h4>Compatibility with older Subversion clients</h4>
 456
 457 <ul>
 458
 459 <li>Older Subversion clients should still be able to commit merges on new
 460     repositories.</li>
 461
 462 <li>Repository administrators should be able to control whether older clients
 463     (which do not support merge tracking) can commit changes to specific (e.g.
 464     branch or tag) subdirectories.</li>
 465
 466 </ul>
 467
 468 </div>  <!-- compatibility -->
 469
 470 <div class="h4" id="versioning">
 471 <h4>Versioning</h4>
 472
 473 <p>Merge tracking information should be maintained for all versions of
 474 files in a repository. Thus, if you create a copy of an old version of
 475 a branch, the merge tracking information will still be accurate.</p>
 476
 477 <p>Changes to merge tracking information should be versioned,
 478 therefore allowing tracking and auditing of changes to merge
 479 tracking data.</p>
 480
 481 </div>  <!-- versioning -->
 482
 483 <div class="h4" id="authz">
 484 <h4>Authorization</h4>
 485
 486 <p>Repository administrators should be able to control whether merge
 487 tracking information can be committed by specific users or to specific
 488 directories.</p>
 489
 490 <p>Repository administrators should be able to control whether changes
 491 can be committed without associated merge-tracking information. Using
 492 this feature, a repository administrator could enforce (for example)
 493 that all changes must be committed to trunk before they are merged to
 494 a release branch.</p>
 495
 496 </div>  <!-- permissions -->
 497
 498 </div>  <!-- misc -->
 499
 500 </div>  <!-- requirements -->
 501 </div>  <!-- h2 -->
 502
 503
 504 <div class="h2" id="related-documents">
 505 <h2>Related Documents and Discussion</h2>
 506
 507 <ul>
 508   <li><a href="http://subversion.tigris.org/merge-tracking/summit.html"
 509   >CollabNet customer Merge Tracking Summit</a></li>
 510
 511   <li><a
 512   href="http://svn.collab.net/repos/svn/trunk/notes/schema-tradeoffs.txt"
 513   >schema-tradeoffs.txt</a>: Search for the section called "Questions
 514   that Users Ask".</li>
 515
 516 <!-- TODO: "Import" from Karl's site:
 517   <li><a href="merge-history/threads.html">Various merging threads
 518   from dev@svn</a></li>
 519
 520   <li><a href="jackr-diff-merge-syntax/threads.html">Mail from Jack
 521   Repenning about diff/merge syntax</a></li>
 522 -->
 523
 524   <li>Bram Cohen <a
 525   href="http://lists.zooko.com/pipermail/revctrl/2005-May/000012.html"
 526   >muses on rename/copy, etc.</a></li>
 527 </ul>
 528
 529 </div>  <!-- related-documents -->
 530
 531 <p>$Date$</p>
 532
 533 </body>
 534 </html>