Updating pull request branch on external EGSnrc forks - nrc-cnrc/EGSnrc GitHub Wiki

Background

When developers submit a pull request (PR) against EGSnrc from their personal EGSnrc fork, it may become necessary for the EGSnrc maintainers to modify the PR branch, for example to enforce code or commit style guides, fix errors, reorganize file location, etc. One obvious solution is to ask the fork owner to perform the required changes and update their PR branch on their fork, which automatically updates the pull request.

However, it is also possible for the maintainers of the PR target repository to push, even push --force-with-lease, directly to the PR branch on the developer's fork! This may seem odd, as you are writing to someone else's repository, yet this is enabled on github for exactly this purpose (it can be disabled by the fork owner, of course). By default, submitting a pull request gives the target repository maintainers write access to the PR branch.

Best practices

Warn the fork owner about branch update in advance, and suggest they create a backup branch (with git branch). Suggest they continue working on a separate branch after the PR is submitted. For example, some developers submit PRs from their own develop or master branches, which they may be using for production runs of EGSnrc on their system! The fork owner should be encouraged in this case to reopen the PR from a dedicated branch. Personnally, I also always keep a backup of the original branch to restore the original branch if needed.

If you need to rewrite the original PR branch commit history, use git push --force-with-lease, and never just --force. That way, if the fork owner has pushed new commits in the mean time, you will not erase them! If --force-with-lease is declined, then it is best to coordinate with the PR author.

Add commits on top of the branch, at least temporarily, then seek the PR author approval for your changes, and finally reorganize or squash the commits as needed.

Example

To set things concretely, let's look at PR #630, where user @ellieb is asking EGSnrc to pull changes from ellieb:feature-dose-viewer, a dedicated branch for this PR on the EGSnrc fork under her account.

In this case the EGSnrc maintainers may push to @ellieb's branch with the following commands, in a local EGSnrc clone:

git remote add ellie [email protected]:ellieb/EGSnrc.git   # add a remote, here called "ellie", pointing to the the ellieb fork
git fetch ellie                                         # fetch the ellie/* branches (confirm with git branch -avv)
git checkout --track ellie/feature-dose-viewer          # checkout the PR branch, named feature-dose-viewer in this case
# ...                                                   # make changes at will, rebase, add or edit commits, etc.
git push                                                # update branch on ellieb's fork! If using the --force-with-lease, warn owner!

The PR in the EGSnrc repository is at this point updated accordingly.