17  Rebase for synchronizing work

Thanks for your contribution; could you rebase this against main? Thanks!

That is also a common request from maintainers, and one that can cause confusion for new contributors.

When one is working on a problem, others may be working in parallel. And their parallel work may be finished before one’s own work is. Thus the starting point for one person’s work (branching point) can “go stale” making it harder to integrate.

While git merge and resolving syntax level conflicts can resolve some of this, it is often easier to understand and review work if it is presented as changes against an updated starting point.

As a concrete example imagine a project to build a dashboard. Imagine that you fork the repo in January to implement a new type of visualization (let’s say a pie chart). You work on this during January and February, finally nailing it down at the start of March. Meanwhile, though, others in the project have spent February introducing a whole new way of accessing databases. By the time you make a pull request at the start of March things have changed a lot since you branched in January.

If you submit a PR without updating, the maintainers will likely ask you to update your branch to make it work with the new database system.

--January-|------February--------------|--March

          __pie_chart_branch___________
         /                             \
main--|--|-----------------------|----|-------
            \                     /
             \__new_database_____/

First thing to do is to update your local repository with the changes from upstream.

git pull upstream main

Then you could try two options:

  1. Either merge main into pie_chart_branch yourself (this is what we did in earlier exercises)
  2. Rebase pie_chart_branch on main (as though pie_chart_branch was created in late February and you did all the work very quickly!)

Option 1 is possible, but often merging your work involves touching parts of the system you don’t know what much about and is better left to the core developers. In addition, merging in this way leaves merge commit messages and some projects really don’t like those because they make the history harder to read. It also leaves all of your “intermediate” commits in the history (things like “fix typo” and “forgot comma”). Some find that too much information.

Option 2 is generally preferred, since it focuses on clear communication via PRs that are easier to read and review. Often this just means a single commit showing the differences between the most updated work and the work that you want to contribute.

Option 2 is called rebase. We specify a new starting point, and git gives us a little UI in which we can choose which commits to include, which to squash, and we can even reorder commits.

Learngitbranching has a tutorial which we will do now. Chose square 2 in the “Moving work around” section (titled Interactive Rebase Intro). https://learngitbranching.js.org/?level=move2

A full git textual introduction is available here https://github.com/openedx/edx-platform/wiki/How-to-Rebase-a-Pull-Request