notes/tree-conflicts/use-cases.txt

   1                                -*- text -*-
   2
   3               TREE CONFLICTS USE CASES AND DESIRED BEHAVIOURS
   4
   5
   6 Issue reference:  http://subversion.tigris.org/issues/show_bug.cgi?id=2282
   7
   8 (These use cases are based on a scenario paper "SVN move/rename
   9 problems & suggested improvements" submitted by a corporate Subversion
  10 user, which may be found attached to issue #2282.)
  11
  12 --------------------------------------------------------------------------
  13
  14 ==========
  15 USE CASE 1
  16 ==========
  17
  18 Description
  19
  20    During an update, a file modification is merged onto a file move.
  21
  22 Current Behavior
  23
  24    Developer A modifies Foo.c and commits it to the repository.
  25
  26    Developer B has simultaneously moved Foo.c to Bar.c in his working
  27    copy.
  28
  29    B cannot commit because the working copy is out of date, so B runs 'svn
  30    update'. The update will apply A's modifications to Foo.c in the
  31    repository to Foo.c in B's working copy.
  32
  33 Problems With Current Behavior
  34
  35    First problem:
  36
  37    A's modification of Foo.c will effectively be reverted by B's new
  38    revision. Foo.c will be deleted in the new revision, and Bar.c will be
  39    added with the content of the original Foo.c before A's modifications.
  40    Hence A will likely get angry with B.
  41
  42    Second problem:
  43
  44    B is not explicitly warned about reverting A's modification of Foo.c.
  45    The only visible warning is that Foo.c is left behind unversioned in
  46    B's working copy because it has "local" modifications (which were in
  47    fact made by A). This will likely escape B's attention.
  48
  49 Diagram of current behavior
  50
  51
  52               (edit)
  53     wcA          -- Foo.c' ------->
  54                 /         |
  55                /          |commit
  56     repos     /           v
  57     -- Foo.c -------------- Foo.c' --------------- Bar.c --->
  58               \                     |          ^
  59                \                    |update    |commit
  60                 \                   v          |
  61     wcB          -- +Bar.c ---------- +Bar.c ----  Bar.c --->
  62              (move) -Foo.c            -Foo.c'     ?Foo.c' (unversioned)
  63
  64
  65 Desired behavior
  66
  67    When user B updates, A's modifications to Foo.c should be merged into
  68    Bar.c. Signal a text conflict if necessary.
  69
  70    Foo.c should be deleted from B's working copy.
  71
  72    A tree conflict should be signalled to inform B of the new changes
  73    to Bar.c, so that B can review the modified Bar.c before committing it.
  74
  75 Diagram of desired behaviour
  76
  77
  78               (edit)
  79     wcA          -- Foo.c' ------->
  80                 /          |
  81                /           |commit
  82     repos     /            v
  83     -- Foo.c --------------- Foo.c' ------------------------ Bar.c' --->
  84               \                      |           ^        ^
  85                \                     |update     |commit  |commit
  86                 \                    v           |(fails) |
  87     wcB          -- +Bar.c ------------ +Bar.c' -------------->
  88              (move) -Foo.c              -Foo.c          ^
  89                                                         |
  90                                                      resolved
  91
  92
  93 ==========
  94 USE CASE 2
  95 ==========
  96
  97 Description
  98
  99    During an update, a file move is merged onto a file modification.
 100
 101    This is essentially the same as Use Case 1, with the difference that
 102    this time, B does the edit and A does the move.
 103
 104 Current Behavior
 105
 106    Developer B modifies Foo.c in his working copy.
 107
 108    Developer A has simultaneously moved Foo.c to Bar.c and commits
 109    the move to the repository.
 110
 111    B cannot commit because his working copy is out of date, so B runs
 112    'svn update'. The next update will add Bar.c (with the same content
 113    as the original Foo.c) to B's working copy, and delete Foo.c from
 114    B's working copy. Since B made local modifications to Foo.c,
 115    it will not be deleted from disk but left behind unversioned.
 116
 117 Problems with Current Behavior
 118
 119    Developer B may not notice that Foo.c fell out of version control.
 120    B's source tree in the working copy likely builds fine because Foo.c
 121    is still present on disk.  So B may commit an incomplete change set,
 122    possibly breaking the tree.  Everybody will get angry with B if this
 123    happens.
 124
 125 Diagram of Current Behaviour
 126
 127
 128               (move)
 129     wcA          -- +Bar.c ------->
 130                 /   -Foo.c |
 131                /           |commit
 132     repos     /            v
 133     -- Foo.c --------------- Bar.c ----------------------->
 134               \                      |            ^
 135                \                     |update      |commit
 136                 \                    v            |(no-op)
 137     wcB          -- Foo.c' ------------  Bar.c  ------->
 138              (edit)                     ?Foo.c' (unversioned)
 139
 140
 141 Desired Behavior
 142
 143    In B's working copy, the update should add Bar.c and merge the local
 144    modifications to Foo.c into Bar.c. Signal a text conflict if necessary.
 145
 146    Foo.c should be deleted from B's working copy.
 147
 148    A tree conflict should be signaled to inform B that Foo.c has been
 149    renamed to Bar.c
 150
 151 Diagram of Desired Behaviour
 152
 153
 154               (move)
 155     wcA          -- +Bar.c ------->
 156                 /   -Foo.c |
 157                /           |commit
 158     repos     /            v
 159     -- Foo.c --------------- Bar.c -------------------------- Bar.c'--->
 160               \                      |          ^          ^
 161                \                     |update    |commit    |commit
 162                 \                    v          |(fails)   |
 163     wcB          -- Foo.c' ------------+Bar.c' ------------------------>
 164              (edit)                    -Foo.c'           ^
 165                                                          |
 166                                                       resolved
 167
 168
 169 ==========
 170 USE CASE 3
 171 ==========
 172
 173 Description
 174
 175    During an update, a file move is merged onto a conflicting file move.
 176
 177 Current Behavior
 178
 179    Developer A moves Foo.c to Bar.c and commits the move to the repository.
 180
 181    Developer B has moved Foo.c to Bix.c in his working copy.
 182
 183    B cannot commit because his working copy is out of date, so B runs
 184    'svn update'. The update will add Bar.c to B's working copy and
 185    delete Foo.c from B's working copy (the latter is a no-op).
 186
 187 Problems with Current Behavior
 188
 189    After B's next commit, the content of the original Foo.c
 190    will exist twice in the source tree under two different paths,
 191    namely Bar.c and Bix.c, respectively.
 192
 193    This may not have been intended.
 194
 195 Diagram of Current Behavior
 196
 197
 198              (move)
 199     wcA          -- +Bar.c ------>
 200                 /   -Foo.c |
 201                /           |commit
 202     archive   /            v
 203     -- Foo.c --------------- Bar.c ------------------ Bar.c --->
 204               \                    |         ^        Bix.c
 205                \                   |update   |commit
 206                 \                  v         |
 207     wcB          -- +Bix.c ---------- +Bix.c ------->
 208              (move) -Foo.c             Bar.c
 209
 210
 211 Desired Behavior
 212
 213    A tree conflict should be signaled to inform B of the conflicting rename
 214    operation. B can now decide on deleting either file or committing both.
 215
 216 Diagram of Desired Behavior
 217
 218
 219              (move)
 220     wcA          -- +Bar.c ------>
 221                 /   -Foo.c |
 222                /           |commit
 223     archive   /            v
 224     -- Foo.c --------------- Bar.c -------------------------- Bar.c -->
 225               \                    |         ^        ^       (or Bix.c,
 226                \                   |update   |commit  |commit  or both)
 227                 \                  v         |(fails) |
 228     wcB          -- +Bix.c ---------- +Bix.c -------------->
 229              (move) -Foo.c             Bar.c        ^
 230                                                     |
 231                                                  resolved
 232
 233
 234 ==========
 235 USE CASE 4
 236 ==========
 237
 238 Description
 239
 240    A file modification is merged onto the source of a file move.
 241
 242 Current Behavior
 243
 244    Developer A modifies Foo.c and commits it to the repository.
 245
 246    Developer B moves Foo.c to Bar.c and commits it to the repository.
 247
 248    Developer merges A's new revision into his working copy. The merge
 249    will apply A's modification to Foo.c to the Foo.c in B's working
 250    copy.
 251
 252 Problems With Current Behavior
 253
 254    First problem:
 255
 256    A's modification of Foo.c will not be merged to B's line of
 257    development because the merge skips the absent file.
 258
 259    Second problem:
 260
 261    B is not explicitly warned about reverting A's modification of Foo.c,
 262    except for a "skipped" warning in the output of the merge command,
 263    which might not be noticed.
 264
 265 Diagram of current behavior
 266
 267
 268             (edit)
 269     urlA        -- Foo.c' ------------------>
 270                /   (r50)              |
 271               /                       |
 272     -- Foo.c -                        |merge -c50
 273               \                       |(Foo.c skipped)
 274                \                      |
 275     urlB        -- +Bar.c ------------|----------------->
 276             (move) -Foo.c \           |         ^
 277                            \          |         |commit
 278                             \         v         |(no-op)
 279     wcB                      -- Bar.c -- Bar.c ------ -->
 280
 281
 282 Desired behavior
 283
 284    When user B merges, A's modifications to Foo.c should be merged into
 285    Bar.c. Signal a text conflict if necessary.
 286
 287    A tree conflict should be signalled to inform B of the new changes
 288    to Bar.c, so that B can review the modified Bar.c before committing it.
 289
 290 Diagram of desired behaviour
 291
 292
 293             (edit)
 294     urlA        -- Foo.c' ------------------>
 295                /   (r50)               |
 296               /                        |
 297     -- Foo.c -                         |merge -c50
 298               \                        |(tree conflict)
 299                \                       |
 300     urlB        -- +Bar.c -------------|-------------------- Bar.c' -->
 301             (move) -Foo.c  \           |          ^        ^
 302                             \          |          |commit  |commit
 303                              \         v          |(fails) |
 304     wcB                       -- Bar.c -- Bar.c' --------------->
 305                                                          ^
 306                                                          |
 307                                                       resolved
 308
 309
 310 ==========
 311 USE CASE 5
 312 ==========
 313
 314 Description
 315
 316    A file move is merged onto a modification of the move-source.
 317
 318    This is essentially the same as Use Case 4, with the difference that
 319    this time, B does the edit and A does the move.
 320
 321 Current Behavior
 322
 323    Developer A  moves Foo.c to Bar.c and commits it to the repository.
 324
 325    Developer B modifies Foo.cand commits it to the repository.
 326
 327    Developer merges A's new revision into his working copy.  The merge
 328    will add Bar.c (with the same content as the original Foo.c) and
 329    will delete B's Foo.c.
 330
 331 Problems With Current Behavior
 332
 333    First problem:
 334
 335    B's has modified Foo.c in the past.  This modification will be lost
 336    unless B reviews the history of Foo.c and Bar.c at both URLs and
 337    corrects the problem (e.g., via 'svn copy').
 338
 339 Diagram of current behavior
 340
 341
 342             (move)
 343     urlA        -- +Bar.c ------------------->
 344                /   -Foo.c              |
 345               /    (r50)               |
 346     -- Foo.c -                         |merge -c50
 347               \                        |
 348                \                       |
 349     urlB        -- Foo.c' -------------|------------ Bar.c --->
 350             (edit)        \            |          ^
 351                            \           |          |commit
 352                             \          v          |
 353     wcB                      -- Foo.c' -- +Bar.c ------>
 354                                           -Foo.c'
 355
 356
 357 Desired behavior
 358
 359    In B's working copy, the update should add Bar.c and merge the local
 360    modifications to Foo.c into Bar.c. Signal a text conflict if necessary.
 361
 362    Foo.c should be deleted from B's working copy.
 363
 364    A tree conflict should be signaled to inform B that Foo.c has been
 365    renamed to Bar.c
 366
 367 Diagram of desired behaviour
 368
 369
 370             (move)
 371     urlA        -- +Bar.c ------------------->
 372                /   -Foo.c              |
 373               /    (r50)               |
 374     -- Foo.c -                         |merge -c50
 375               \                        |(tree conflict)
 376                \                       |
 377     urlB        -- Foo.c' -------------|-------------------- Bar.c'-->
 378             (edit)        \            |          ^        ^
 379                            \           |          |commit  |commit
 380                             \          v          |(fails) |
 381     wcB                      -- Foo.c' -- Bar.c' --------------->
 382                                          -Foo.c'         ^
 383                                                          |
 384                                                       resolved
 385
 386
 387 ==========
 388 USE CASE 6
 389 ==========
 390
 391 Description
 392
 393    A file move is merged onto a conflicting file move.
 394
 395 Current Behavior
 396
 397    Developer A moves Foo.c to Bar.c and commits it to the repository.
 398
 399    Developer B moves Foo.c to Bix.c and commits it to the repository.
 400
 401    Developer merges A's new revision into his working copy.  The merge
 402    will add Bar.c with history in B's working copy.
 403
 404 Problems With Current Behavior
 405
 406    After B's next commit, the content of the original Foo.c will exist
 407    twice in the source tree under two different paths (Bar.c and
 408    Bix.c).  This may not have been intended.
 409
 410 Diagram of current behavior
 411
 412
 413             (move)
 414     urlA        -- +Bar.c ------------------>
 415                /   -Foo.c             |
 416               /    (r50)              |
 417     -- Foo.c -                        |merge -c50
 418               \                       |
 419                \                      |
 420     urlB        -- +Bix.c ------------|---------------- Bix.c --->
 421             (move) -Foo.c \           |         ^       Bar.c
 422                            \          |         |commit
 423                             \         v         |
 424     wcB                      -- Bix.c -- Bix.c ---------->
 425                                         +Bar.c
 426
 427
 428 Desired behavior
 429
 430    A tree conflict should be signaled to inform B of the conflicting
 431    rename operation.  B can delete either file or commit both.
 432
 433 Diagram of desired behaviour
 434
 435
 436             (move)
 437     urlA        -- +Bar.c ----------------->
 438                /   -Foo.c             |
 439               /    (r50)              |
 440     -- Foo.c -                        |merge -c50
 441               \                       |(tree conflict)
 442                \                      |
 443     urlB        -- +Bix.c ------------|------------------------- Bar.c -->
 444             (move) -Foo.c \           |         ^        ^       (or Bix.c,
 445                            \          |         |commit  |commit  or both)
 446                             \         v         |(fails) |
 447     wcB                      -- Bix.c -- Bix.c -------------->
 448                                         +Bar.c          ^
 449                                                         |
 450                                                      resolved
 451