This page describes a hypothetical situation that could arise with the sage git workflow, as discussed on TentativeConventions and at Sage Days 54.

Why can rebasing cause problems?

Consider the following scenario, and the accompanying ascii art diagrams:

• Sage development happens, and the origin/master branch gets to a certain commit M.

---K---L---M  <-(origin/master)

• Developer Alice comes along and decides to work on a new feature, say aardvarks, starting from the current official origin/master branch.

---K---L---M  <-(origin/master)
            \
             --A---B---C  <-(aardvarks)

• Developer Bob sees that the aardvarks feature looks nice, and starts work on a new feature, say bowling, which depends on aardvarks.

---K---L---M  <-(origin/master)
            \
             --A---B---C  <-(aardvarks)
                        \
                         --X---Y---Z  <-(bowling)

• Sage development continues, and some other features are merged meanwhile into origin/master.

---K---L---M---P---Q---R---S---T  <-(origin/master)
            \
             --A---B---C  <-(aardvarks)
                        \
                         --X---Y---Z  <-(bowling)

• Alice doesn't know about Bob's bowling feature, and thinks (correctly or not) that it would be better if the aardvarks feature was based on the latest official origin/master, that is commit T, instead of commit M. Instead of merging commit T into the aardvarks branch, Alice does a rebase. This creates a new history A2--B2--C2 based at T instead of the original A---B---C based at M.

---K---L---M---P---Q---R---S---T  <-(origin/master)
            \                   \
             \                   --A2--B2--C2  <-(aardvarks)
              \
               A---B---C
                        \
                         --X---Y---Z  <-(bowling)

• The aardvarks feature is ready and has a positive review, so it is merged into the official origin/master.

---K---L---M---P---Q---R---S---T----------------U  <-(origin/master)
            \                   \              /
             \                   --A2--B2--C2--  <-(aardvarks)
              \
               A---B---C
                        \
                         --X---Y---Z  <-(bowling)

• The bowling feature is ready and has a positive review, so it is merged into the official origin/master. However, at this point the commits A---B---C create a merge conflict with the seemingly identical commits A2--B2--C2. They are only seemingly identical, because they don't appear at the same location in the git tree (they have different parents). However, of course they touch the same code files, and in the same regions too.

---K---L---M---P---Q---R---S---T----------------U---*  <-(origin/master)
            \                   \              /   /
             \                   --A2--B2--C2--   /    <-(aardvarks)
              \                                  /
               A---B---C                        /
                        \                      /
                         --X---Y---Z-----------  <-(bowling)

Now, there is a problem, because the bowling code does not merge cleanly into the official origin/master branch. Regardless of who is right or wrong, this needs to be fixed before the positively reviewed bowling branch can be merged into origin/master. The question here is: whose responsibility is it to fix the problem?

• If the commits A---B---C in the aardvarks branch were marked as belonging to Alice only, then Bob could foresee the possibility that Alice messes with these commits (in the example, by rebasing them), so Bob should be responsible for fixing the mess created by basing his work on someone else's unstable work-in-progress.

• If the commits A---B---C were marked as belonging to the whole community, then Alice could foresee that other may use the code (even if she doesn't see it on Trac yet), so Alice should be responsible for fixing the mess created by changing what the community saw as stable (even if it was pre-review) history of code on the server.

So, the central question is, when does the aardvarks branch change from belonging to Alice only, to belonging to the whole community?

What happens with merging instead of rebasing?

Here is what would happen in the scenario above if Alice merged instead of rebasing:

• The story is the same until Sage development gets to the commit T.

---K---L---M---P---Q---R---S---T  <-(origin/master)
            \
             --A---B---C  <-(aardvarks)
                        \
                         --X---Y---Z  <-(bowling)

• Alice doesn't know about Bob's bowling feature, but still wants aardvarks to incorporate the latest official origin/master, that is commit T, instead of commit M. Alice merges T into the aardvarks branch.

---K---L---M---P---Q---R---S---T  <-(origin/master)
            \                   \
             --A---B---C---------D  <-(aardvarks)
                        \
                         --X---Y---Z  <-(bowling)

• The aardvarks feature is ready and has a positive review, so it is merged into the official origin/master. Any merge conflicts were resolved in the commit D, so this is a clean merge.

---K---L---M---P---Q---R---S---T---U  <-(origin/master)
            \                   \ /
             --A---B---C---------D  <-(aardvarks)
                        \
                         --X---Y---Z  <-(bowling)

• The bowling feature is ready and has a positive review, so it is merged into the official origin/master. At this point, the commits A---B---C are in the common history of U and Z, so there is no conflict there. If X---Y---Z and D do not introduce a further conflict, the merge into V is a clean merge.

---K---L---M---P---Q---R---S---T---U---V  <-(origin/master)
            \                   \ /   /
             --A---B---C---------D   /    <-(aardvarks)
                        \           /
                         --X---Y---Z  <-(bowling)