Rebasing a PR

Always follow the rebase process whenever possible.

What is a rebase?

Rebasing is the preferred strategy for applying PRs tp the staging branch (or any base branch). Rather than merging different people's work together, it takes the latest available commit on the base branch and then tries to replay all of the current branches work done on top of that. This stacks all the commits made by one person together neatly and helps with tracking changes.

The most common use case for rebasing is when a PR has become out of date and one or more pages has edits from someone else on a different task. Rebasing allows an interactive session in which merge conflicts are presented so that those conflicts can be handled one by one.

Within the docs, typically, you will only ever rebase your own work to update it with the latest work done on staging. When done often, it can help prevent merge conflicts when it comes time to merge the PR to staging.

If you PR has ended up with merge conflicts by the time it is ready for publishing, fear not, the docs team will do the rebase before merging.

Ensure that the base branch is up to date

For the docs repo, this is usually staging, but could be any base branch.

git checkout staging
git fetch
git status (must be clean)
git pull

Check out the branch that needs to be updated

If this was from a PR, just click the icon near the top of the github page to copy the branch name, for example ck/DCOS-2222. Or, if you are just rebasing your own work, checkout the branch that you are working on.

git checkout ck/DCOS-2222

Start the rebase

This will try to put your work on top of the last commit of that base branch. For example, a PR that had a conflict would need to be updated with the latest from staging. Your command line should look something like this:

techie@docs-macbook dcos-docs-site (techie/update-builds) $ git rebase <base branch>

The actual command to run:

git rebase staging

Handle rebase merge conflicts

If you encounter merge conflicts, the order of operations is slightly different when in rebase mode. Git will run through each of the commits on the base branch in order and check for conflicts against the working branch. If one is found, it will stop and provide instructions. Repeat this process for each merge conflict that it stops on until it finishes working through all the commits it has to check.

1. Find the file(s) that have conflicts
   
2. Resolve any conflicts and save the files
3. Add file to git staging area

   • Click the + sign in the GUI next to the file name
     

   • OR git add .

4. Continue the rebase git rebase --continue
5. This will continue working through all the commits until complete.

NB: Often you need to make choices and something might go wrong. git rebase --abort any time before it finishes will cancel and reset you to where you were.

The following steps refer to using VSCode editor.

Pushing a rebased branch to staging

Whenever a rebase occurs, or a few other operations that change the order of commits as they are saved to the branch, git will raise an error if you try to push those changes up to the remote repository (usually called origin by default). This is because the histories are incompatible and this is a protective measure against major changes.

Override the history protection with the --force flag

git push --force origin <branchname>

Interactive Rebasing

It is possible to force an interactive rebase should you want to pick and choose which work from the other branch should be applied to yours. (Advanced)

git rebase -i <commit/branch>

Git and merges

Understand the three ways git merges things

Normally, you won't need to merge things together on your own. But, git uses merges for other operations, so it is important to have a good understanding of working with them, especially if a conflict occurs.

• trivial merge (feature branch is an ancestor)
• fast-forward merge (feature branch is ahead)
• divergent merge (both branches have added commits that affect the same lines)

Merging a separate branch into the one you are on

From the branch you want to apply the changes to:
git merge <otherbranch> This calls the other branch to merge it into the one you are currently working on.

This intersperses your work commits along a time axis against other work performed on the same branch. You may be asked to handle merge conflicts if there has been a divergence.

This is only recommended as a last resort to rebasing.