6. Merge a Documentation Pull Request

Owned by Sylvia Pearce (Deactivated)
Last updated: Apr 03, 2023 by Feanil Patel
4 min read

Merge a pull request (GitHub on the Web)

When you get approval for your changes from at least one doc team member ("thumbs up" sign by typing :+1: in the comment field) and one engineer/PM/other SME, you can merge your changes into the master branch for release. 

  1. Check the end of the comments on the "Conversation" tab of your pull request to see if you can merge your changes immediately, or if there are conflicts. If there are conflicts, you must rebase (fix the conflicts) before you continue. If your branch has merge conflicts, the GitHub pull request interface displays This branch has conflicts that must be resolved.
  2. Check the "Commits" link/tab for your branch. It shows the number of commits you made for the branch. If this number is >1, you must squash your commits before you merge the PR.
  3. Check the end of the comments on the "Conversation" tab again just to make sure that "All is well – tests passed". This is critical if you have edited error/warning messages or other UI strings, or otherwise affected a .py or .js file.
  4. Click Merge Pull Request to merge the changes.
  5. When all changes are merged, you'll see a Merged notification and a Closed notification above a note that informs you that it's safe to delete the working branch you were using. 
  6. Click Delete branch to delete the branch.
    Note: You might also need to delete the branch separately in the GitHub Desktop application. There is a time lag of 15+ minutes before you'll be able to do this.

Rebase (Terminal)

 While you make changes on your branch, others are making changes on their own branches. When the same file gets changed in different branches, you end up with a conflict. "Rebase" is the way to fix the conflict.


  1. Open Terminal on the Mac and change directories to the repository where you have your branch.
  2. Commit all local changes on your branch.
    git add {changed files}
    git commit -m "Checkpoint commit" 

  3. Get changes from the remote repository. 
    git fetch

  4. Integrate changes from the remote repository into your working copy.
    git rebase origin/master

  5. This lists the names of files that have conflicts, and inserts identifiers directly into those files.

  6. Open each RST file that has a conflict, find the "HEAD" identifiers, fix the conflict, remove the identifiers, and save.
  7. Enter the command: 
    git add <filename>
  8. Iterate through steps 5 & 6 for every file that has a conflict.
  9. Enter the command: 
    git rebase --continue
  10. Enter git status at any time to see the status of your branch. You'll be able to see whether more conflicts remain, or whether your branch is up to date.

  11. When no more conflicts remain, push your changes to the remote repository.

    git push -f

    The -f argument to force push is required because the rebase command alters the git history in a way that doesn't match the history on the remote branch. If you try to push without the force argument, git will reject your attempt and suggest that you git pull. Don't git pull, whatever you do.

Reference: Git Rebase Lunch + Learn, also see end of this page for some external references. 

Squash commits (Terminal and Sublime)

DB needs to do some setup on your Mac for this to open Sublime. (It still works otherwise, but opens a VI editor instead of Sublime. Good luck if so, and remember that Esc+ZZ is your friend.)

  1. Open Terminal on the Mac and change directories to the repo/branch for the PR for which you are squashing commits.
  2. Rebase against master before squashing commits:

    git status
    git fetch
    git rebase origin/master

    If you see "Current branch <branchname> is up to date", you're all set. If you see "Your branch and origin/<branchname> have diverged and have x and x different commits each, respectively", you should push your local changes. DO NOT follow the help and git pull.

    git push -f

    You should then see "Current branch <branchname> is up to date"


    Only from this state should you squash commits.


  3. Refresh your PR page in Github to make sure you are seeing the final number of commits made in that PR.

  4. Enter the command: 
    git rebase -i HEAD~3
    where the number after the tilde is the number of commits for your branch. A Sublime/text editor window opens.
  5. The top n lines in the file start with the word "pick", where n is that same number of commits. Skip the first line, and then change "pick" to "squash" or "s" on each subsequent line.
  6. Save and close the file. Another Sublime/text editor window opens.
  7. The descriptions you entered for each commit are listed at the top of the file. Delete all but one of them. Edit the description for the single commit to appropriately capture the changes you made in the PR as a whole. Save the file.
  8. Return to Terminal and enter the commands:
    git status
    git push -f
    The PR in Github will refresh to show only one commit, with the description that you chose in Step 6.

    Wait for final tests to run cleanly, then you can merge the PR.

Publish your documentation changes

Merging your changes adds them to the master branch for the project on Github, but does not publish them to the online help guides. Contact a doc team member to publish your changes so that they will be available in the relevant online guides. 

Links