From b3d268fa14cd1d19ac7ce337425602944b6e52b3 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Sat, 12 Jul 2014 01:32:31 -0400 Subject: [PATCH] DOC : moved rebase docs -> development_workflow - this will likely create an annoying conflict, yay --- doc/devel/coding_guide.rst | 135 -------------------- doc/devel/gitwash/development_workflow.rst | 136 +++++++++++++++++++++ 2 files changed, 136 insertions(+), 135 deletions(-) diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst index db45b9bfe0e5..ee1fdb9ffef0 100644 --- a/doc/devel/coding_guide.rst +++ b/doc/devel/coding_guide.rst @@ -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 -`. The numpy team has also -`documented how to do this -` -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 ..." to unstage) - (use "git add ..." 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 ..." 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 diff --git a/doc/devel/gitwash/development_workflow.rst b/doc/devel/gitwash/development_workflow.rst index 6bc15bc0125c..dac7034b279a 100644 --- a/doc/devel/gitwash/development_workflow.rst +++ b/doc/devel/gitwash/development_workflow.rst @@ -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 +`. The numpy team has also +`documented how to do this +` +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 ..." to unstage) + (use "git add ..." 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 ..." 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 =========================================================