Skip to content

Commit

Permalink
DOC : moved rebase docs -> development_workflow
Browse files Browse the repository at this point in the history 
 - this will likely create an annoying conflict, yay
  • Loading branch information
@tacaswell
tacaswell committed Sep 16, 2016
1 parent bb8525e commit b3d268f
Show file tree
Hide file tree
Showing 2 changed files with 136 additions and 135 deletions.
135 changes: 0 additions & 135 deletions doc/devel/coding_guide.rst
View file
Expand Up @@ -163,141 +163,6 @@ C/C++ extensions
docstrings, and the Numpydoc format is well understood in the
scientific Python community.

Rebasing a Pull Request (PR)
----------------------------

When working on a PR, changes may occur in the parent branch (usually master).
This can lead to conflict with changes in your branch. The conflicts can be
trivial: for example both the parent branch and your branch add an entry to
the top of `CHANGELOG`. Git can not unambiguously tell what to with both
changes (should one go above the other? if so, which order? should it try to
merge them?) so it declares the branches can not be merged
cleanly. Github can only automatically merge PR without conflicts, so you will
need to manually 'rebase'. This is the process of updating your branch with
upstream changes, and resolving conflicts.

In git, rebasing is a mild form of re-writing history: it effectively forwards
all your commits to the updated upstream commit. For a much more detailed
explanation (with pictures!) see `this nice write up
<http://git-scm.com/book/en/Git-Branching-Rebasing>`. The numpy team has also
`documented how to do this
<http://docs.scipy.org/doc/numpy/dev/gitwash/development_workflow.html#rebasing-on-master>`
In general, re-writing history, particularly published history, is considered
bad practice, but in this case it is very useful.

The following example assumes that the remote of _your_ github
repository is called `github` and the remote of the official
repository is called `matplotlib`.

The first step is to make sure that your local copy of the upstream repository is
up-to-date::

$ git fetch matplotlib

This updates your local copy of the repository, but does not change any files
in your working copy. Next, switch to the branch that you want to update::

$ git checkout backend_plt_refactor

You are now ready to start the rebase of your branch onto the target
parent branch, in this case `matplotlib/master` ::

$ git rebase matplotlib/master

and git will then give a bunch of feed back::

First, rewinding head to replay your work on top of it...
Applying: first steps to extract FigureManager* and friends from pyplot
Applying: split backend_qt4 into two parts, with and without Gcf
...
Applying: pep8 clean up on backend_gtk3.py
Using index info to reconstruct a base tree...
M lib/matplotlib/backends/backend_gtk3.py
Falling back to patching base and 3-way merge...
Auto-merging lib/matplotlib/backends/backend_gtk3.py
CONFLICT (content): Merge conflict in lib/matplotlib/backends/backend_gtk3.py
Failed to merge in the changes.
Patch failed at 0013 pep8 clean up on backend_gtk3.py
The copy of the patch that failed is found in:
/home/tcaswell/other_source/matplotlib/.git/rebase-apply/patch

When you have resolved this problem, run "git rebase --continue".
If you prefer to skip this patch, run "git rebase --skip" instead.
To check out the original branch and stop rebasing, run "git rebase --abort".

A number of commits could be cleanly applied to
the tip of `matplotlib/master`, however, git eventually hits a commit
that had conflicts. In this case in the file
`lib/matplotlib/backends/backend_gtk3.py`. For more verbose information run ::

$ git status

You are currently rebasing branch 'backend_plt_refactor' on 'e6f8993'.
(fix conflicts and then run "git rebase --continue")
(use "git rebase --skip" to skip this patch)
(use "git rebase --abort" to check out the original branch)

Unmerged paths:
(use "git reset HEAD <file>..." to unstage)
(use "git add <file>..." to mark resolution)

both modified: lib/matplotlib/backends/backend_gtk3.py

no changes added to commit (use "git add" and/or "git commit -a")

This tells you exactly where the conflict is and provides some advice
on how to proceed. Opening up the file in question, you will see
blocks that look something like this::

<<<<<<< HEAD
=======
self.__dict__.clear() # Is this needed? Other backends don't have it.
>>>>>>> pep8 clean up on backend_gtk3.py

The block of code between `<<<<<<<` and `=======` is the code on the
target branch (in this case nothing) and the code between `=======`
and `>>>>>>>` is the code on your branch. The rest of the code is the
same between the two branches. You need to determine how to resolve the
conflict (in this case, the code on HEAD is correct). Once you have
resolved all the conflicts, `add` the file to the index::

$ git add lib/matplotlib/backends/backend_gtk3.py

Repeat this for all of the files that have conflicts. When you are done with
that you can check the status::

$ git status
rebase in progress; onto e6f8993
You are currently rebasing branch 'backend_plt_refactor' on 'e6f8993'.
(all conflicts fixed: run "git rebase --continue")

Changes to be committed:
(use "git reset HEAD <file>..." to unstage)

modified: lib/matplotlib/backends/backend_gtk3.py

which shows us that we have resolved all of the conflicts with this
commit and can continue::

$ git rebase --continue

You now iterate the until you have made it through all of the commits
which have conflicts. Once you have successfully rebased your branch,
be sure to re-run the tests to make sure everything is still working
properly.

Your branch is now rebased, however, because of the way git
determines the hash of each commit, it now shares no commits with your
old branch published on github so you can not push to that branch as
you would when simply adding commits. In order to publish your newly
rebased (and tested!) branch you need to use the `--force` flag::

$ git push --force github

which will _replace_ all of the commits under your branch on github
with the new versions of the commit.

Congratulations, you have rebased your branch!


Style guide
Expand Down
136 changes: 136 additions & 0 deletions doc/devel/gitwash/development_workflow.rst
View file
Expand Up @@ -144,6 +144,142 @@ sure your pull request is ready for merging.
thread.


Rebasing a Pull Request (PR)
============================

When working on a PR, changes may occur in the parent branch (usually master).
This can lead to conflict with changes in your branch. The conflicts can be
trivial: for example both the parent branch and your branch add an entry to
the top of `CHANGELOG`. Git can not unambiguously tell what to with both
changes (should one go above the other? if so, which order? should it try to
merge them?) so it declares the branches can not be merged
cleanly. Github can only automatically merge PR without conflicts, so you will
need to manually 'rebase'. This is the process of updating your branch with
upstream changes, and resolving conflicts.

In git, rebasing is a mild form of re-writing history: it effectively forwards
all your commits to the updated upstream commit. For a much more detailed
explanation (with pictures!) see `this nice write up
<http://git-scm.com/book/en/Git-Branching-Rebasing>`. The numpy team has also
`documented how to do this
<http://docs.scipy.org/doc/numpy/dev/gitwash/development_workflow.html#rebasing-on-master>`
In general, re-writing history, particularly published history, is considered
bad practice, but in this case it is very useful.

The following example assumes that the remote of _your_ github
repository is called `github` and the remote of the official
repository is called `matplotlib`.

The first step is to make sure that your local copy of the upstream repository is
up-to-date::

$ git fetch matplotlib

This updates your local copy of the repository, but does not change any files
in your working copy. Next, switch to the branch that you want to update::

$ git checkout backend_plt_refactor

You are now ready to start the rebase of your branch onto the target
parent branch, in this case `matplotlib/master` ::

$ git rebase matplotlib/master

and git will then give a bunch of feed back::

First, rewinding head to replay your work on top of it...
Applying: first steps to extract FigureManager* and friends from pyplot
Applying: split backend_qt4 into two parts, with and without Gcf
...
Applying: pep8 clean up on backend_gtk3.py
Using index info to reconstruct a base tree...
M lib/matplotlib/backends/backend_gtk3.py
Falling back to patching base and 3-way merge...
Auto-merging lib/matplotlib/backends/backend_gtk3.py
CONFLICT (content): Merge conflict in lib/matplotlib/backends/backend_gtk3.py
Failed to merge in the changes.
Patch failed at 0013 pep8 clean up on backend_gtk3.py
The copy of the patch that failed is found in:
/home/tcaswell/other_source/matplotlib/.git/rebase-apply/patch

When you have resolved this problem, run "git rebase --continue".
If you prefer to skip this patch, run "git rebase --skip" instead.
To check out the original branch and stop rebasing, run "git rebase --abort".

A number of commits could be cleanly applied to
the tip of `matplotlib/master`, however, git eventually hits a commit
that had conflicts. In this case in the file
`lib/matplotlib/backends/backend_gtk3.py`. For more verbose information run ::

$ git status

You are currently rebasing branch 'backend_plt_refactor' on 'e6f8993'.
(fix conflicts and then run "git rebase --continue")
(use "git rebase --skip" to skip this patch)
(use "git rebase --abort" to check out the original branch)

Unmerged paths:
(use "git reset HEAD <file>..." to unstage)
(use "git add <file>..." to mark resolution)

both modified: lib/matplotlib/backends/backend_gtk3.py

no changes added to commit (use "git add" and/or "git commit -a")

This tells you exactly where the conflict is and provides some advice
on how to proceed. Opening up the file in question, you will see
blocks that look something like this::

<<<<<<< HEAD
=======
self.__dict__.clear() # Is this needed? Other backends don't have it.
>>>>>>> pep8 clean up on backend_gtk3.py

The block of code between `<<<<<<<` and `=======` is the code on the
target branch (in this case nothing) and the code between `=======`
and `>>>>>>>` is the code on your branch. The rest of the code is the
same between the two branches. You need to determine how to resolve the
conflict (in this case, the code on HEAD is correct). Once you have
resolved all the conflicts, `add` the file to the index::

$ git add lib/matplotlib/backends/backend_gtk3.py

Repeat this for all of the files that have conflicts. When you are done with
that you can check the status::

$ git status
rebase in progress; onto e6f8993
You are currently rebasing branch 'backend_plt_refactor' on 'e6f8993'.
(all conflicts fixed: run "git rebase --continue")

Changes to be committed:
(use "git reset HEAD <file>..." to unstage)

modified: lib/matplotlib/backends/backend_gtk3.py

which shows us that we have resolved all of the conflicts with this
commit and can continue::

$ git rebase --continue

You now iterate the until you have made it through all of the commits
which have conflicts. Once you have successfully rebased your branch,
be sure to re-run the tests to make sure everything is still working
properly.

Your branch is now rebased, however, because of the way git
determines the hash of each commit, it now shares no commits with your
old branch published on github so you can not push to that branch as
you would when simply adding commits. In order to publish your newly
rebased (and tested!) branch you need to use the `--force` flag::

$ git push --force github

which will _replace_ all of the commits under your branch on github
with the new versions of the commit.

Congratulations, you have rebased your branch!

Staying up to date with changes in the central repository
=========================================================

Expand Down

0 comments on commit b3d268f

Please sign in to comment.