From 41e4c82f193b8326738bc629f387b298a5879600 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Fri, 17 Jan 2014 15:20:14 -0500 Subject: [PATCH 01/10] DOC : draft of text for rebasing doc --- doc/devel/coding_guide.rst | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst index 2ed7a0309720..cd81e0054b5f 100644 --- a/doc/devel/coding_guide.rst +++ b/doc/devel/coding_guide.rst @@ -163,6 +163,34 @@ C/C++ extensions docstrings, and the Numpydoc format is well understood in the scientific Python community. +Rebase a Pull Request +---------------------- + +When working on PR it is possible for other changes to get merged into +the parent branch that conflict with your branch. The conflict can be +trivial, for example both the parent branch and you 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 gives up and declare the +branches can not be merged cleanly. If you were the branches at the +command line you could do an interactive merge where git pauses half +way through to give you a chance to resolve the conflicts by hand, +however using github almost all of the merges back into the parent +branches are done via the web-interface, so only PRs which will +cleanly merged will be accepted. If this happens to your PR, one of +the developers will ask you to 'rebase' your branch which is the +process by which you resolve the conflicts between your branch and +the parent branch. + +In git rebasing is a mild form of re-writing history, as it +effectively transplants where your branch from where you intially +forked of off the parent branch to some other point. For a much more +detailed explanation (with pictures!) see +http://git-scm.com/book/en/Git-Branching-Rebasing. In general, +re-writing history (particularly published history) is considered very +bad, but in this case is very useful. + + Style guide =========== From 5d0c64d37cc4a51f27f2765dfbe7075a4b484ff1 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Sat, 18 Jan 2014 00:42:03 -0500 Subject: [PATCH 02/10] rest of draft for rebase documentation. --- doc/devel/coding_guide.rst | 158 ++++++++++++++++++++++++++++++++----- 1 file changed, 139 insertions(+), 19 deletions(-) diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst index cd81e0054b5f..f66bde71fe7c 100644 --- a/doc/devel/coding_guide.rst +++ b/doc/devel/coding_guide.rst @@ -166,29 +166,149 @@ C/C++ extensions Rebase a Pull Request ---------------------- -When working on PR it is possible for other changes to get merged into -the parent branch that conflict with your branch. The conflict can be -trivial, for example both the parent branch and you 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 gives up and declare the -branches can not be merged cleanly. If you were the branches at the -command line you could do an interactive merge where git pauses half -way through to give you a chance to resolve the conflicts by hand, -however using github almost all of the merges back into the parent -branches are done via the web-interface, so only PRs which will -cleanly merged will be accepted. If this happens to your PR, one of -the developers will ask you to 'rebase' your branch which is the -process by which you resolve the conflicts between your branch and -the parent branch. +When working on a PR it is possible for other changes to get merged +into the parent branch that conflict with changes on 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 gives +up and declare the branches can not be merged cleanly. If you were +the branches at the command line you could do an interactive merge +where git pauses half way through to give you a chance to resolve the +conflicts by hand, however using github almost all of the merges back +into the parent branches are done via the web-interface, so only PRs +which will cleanly merged will be accepted. If this happens to your +PR, one of the developers will ask you to 'rebase' your branch which +is the process by which you resolve the conflicts between your branch +and the parent branch. In git rebasing is a mild form of re-writing history, as it effectively transplants where your branch from where you intially forked of off the parent branch to some other point. For a much more -detailed explanation (with pictures!) see -http://git-scm.com/book/en/Git-Branching-Rebasing. In general, -re-writing history (particularly published history) is considered very -bad, but in this case is very useful. +detailed explanation (with pictures!) see `this nice write up +`. In general, +re-writing history, particularly published history, is considered +bad form, 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 `upstream`. + +The first step is to make sure that your local copy of the upstream repository is +up-to-date:: + + $ git fetch upstream + +which 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 rebase:: + + $ git checkout backend_plt_refactor + +You are now ready to start the rebase of your branch onto the target +parent branch, in this case `upstream/master` :: + + $ git rebase upstream/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: split backend_qt4agg into two parts. + Applying: Added a demo-file to show how to use the FigureManager classes to + Applying: removed un-needed import of Gcf + Applying: pep8 on backend_gtk.py + Applying: pep8 clean up in backend_gdk + Applying: removed un-needed Gcf import + Applying: split backend_gcf into two parts, + Applying: pep8 on backend_gtkagg.py + Applying: split backend_gktagg.py in to two parts + Applying: updated exclude list + 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 `upstream/master`, however, git eventualy hit 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 exactly where the conflict is and 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 we 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. + +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 re-based 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 re-based your branch! Style guide From 51bc33a8941969192444f37c7561459be3bbd547 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Wed, 29 Jan 2014 20:58:57 -0500 Subject: [PATCH 03/10] added numpy link --- doc/devel/coding_guide.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst index f66bde71fe7c..27b97c715f44 100644 --- a/doc/devel/coding_guide.rst +++ b/doc/devel/coding_guide.rst @@ -186,9 +186,11 @@ In git rebasing is a mild form of re-writing history, as it effectively transplants where your branch from where you intially forked of off the parent branch to some other point. For a much more detailed explanation (with pictures!) see `this nice write up -`. In general, -re-writing history, particularly published history, is considered -bad form, but in this case it is very useful. +`. The numpy team +has also `documented how to do this +` +In general, re-writing history, particularly published history, is +considered bad form, 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 From 42ec6a538854d56f98b8b3945456ebce3c89b087 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Fri, 11 Jul 2014 10:59:40 -0500 Subject: [PATCH 04/10] Small rewrite of the rebase PR --- doc/devel/coding_guide.rst | 53 +++++++++++++++++--------------------- 1 file changed, 23 insertions(+), 30 deletions(-) diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst index 27b97c715f44..1a836f2c26d1 100644 --- a/doc/devel/coding_guide.rst +++ b/doc/devel/coding_guide.rst @@ -163,34 +163,27 @@ C/C++ extensions docstrings, and the Numpydoc format is well understood in the scientific Python community. -Rebase a Pull Request ----------------------- - -When working on a PR it is possible for other changes to get merged -into the parent branch that conflict with changes on 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 gives -up and declare the branches can not be merged cleanly. If you were -the branches at the command line you could do an interactive merge -where git pauses half way through to give you a chance to resolve the -conflicts by hand, however using github almost all of the merges back -into the parent branches are done via the web-interface, so only PRs -which will cleanly merged will be accepted. If this happens to your -PR, one of the developers will ask you to 'rebase' your branch which -is the process by which you resolve the conflicts between your branch -and the parent branch. - -In git rebasing is a mild form of re-writing history, as it -effectively transplants where your branch from where you intially -forked of off the parent branch to some other point. For a much more -detailed explanation (with pictures!) see `this nice write up -`. The numpy team -has also `documented how to do this +Rebasing a Pull Request +----------------------- + +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 form, but in this case it is very useful. +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 @@ -201,8 +194,8 @@ up-to-date:: $ git fetch upstream -which 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 rebase:: +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 @@ -242,7 +235,7 @@ and git will then give a bunch of feed back:: 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 `upstream/master`, however, git eventualy hit a commit +the tip of `upstream/master`, however, git eventually hit a commit that had conflicts. In this case in the file `lib/matplotlib/backends/backend_gtk3.py`. For more verbose information run :: From bb8525e15715be927a876197c2d4c810a783454a Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Sat, 12 Jul 2014 01:31:01 -0400 Subject: [PATCH 05/10] DOC : address issues with text to improve clarity --- doc/devel/coding_guide.rst | 48 +++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 27 deletions(-) diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst index 1a836f2c26d1..db45b9bfe0e5 100644 --- a/doc/devel/coding_guide.rst +++ b/doc/devel/coding_guide.rst @@ -163,8 +163,8 @@ C/C++ extensions docstrings, and the Numpydoc format is well understood in the scientific Python community. -Rebasing a Pull Request ------------------------ +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 @@ -187,12 +187,12 @@ 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 `upstream`. +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 upstream + $ 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:: @@ -200,25 +200,16 @@ 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 `upstream/master` :: +parent branch, in this case `matplotlib/master` :: - $ git rebase upstream/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: split backend_qt4agg into two parts. - Applying: Added a demo-file to show how to use the FigureManager classes to - Applying: removed un-needed import of Gcf - Applying: pep8 on backend_gtk.py - Applying: pep8 clean up in backend_gdk - Applying: removed un-needed Gcf import - Applying: split backend_gcf into two parts, - Applying: pep8 on backend_gtkagg.py - Applying: split backend_gktagg.py in to two parts - Applying: updated exclude list + ... Applying: pep8 clean up on backend_gtk3.py Using index info to reconstruct a base tree... M lib/matplotlib/backends/backend_gtk3.py @@ -235,7 +226,7 @@ and git will then give a bunch of feed back:: 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 `upstream/master`, however, git eventually hit a commit +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 :: @@ -254,8 +245,9 @@ that had conflicts. In this case in the file no changes added to commit (use "git add" and/or "git commit -a") -This exactly where the conflict is and some advice on how to proceed. Opening -up the file in question, you will see blocks that look something like this:: +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 ======= @@ -272,7 +264,7 @@ 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 we can check the status:: +that you can check the status:: $ git status rebase in progress; onto e6f8993 @@ -290,20 +282,22 @@ commit and can continue:: $ git rebase --continue You now iterate the until you have made it through all of the commits -which have conflicts. +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 re-based branch you need to -use the `--force` flag:: +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 re-based your branch! +Congratulations, you have rebased your branch! Style guide From b3d268fa14cd1d19ac7ce337425602944b6e52b3 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Sat, 12 Jul 2014 01:32:31 -0400 Subject: [PATCH 06/10] 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 ========================================================= From 3c7e53991f960e775641ca3700ecbff4fad1176c Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Wed, 14 Sep 2016 22:04:42 -0700 Subject: [PATCH 07/10] FIX github -> GitHub --- doc/devel/gitwash/development_workflow.rst | 72 ++++++++++++++++------ 1 file changed, 52 insertions(+), 20 deletions(-) diff --git a/doc/devel/gitwash/development_workflow.rst b/doc/devel/gitwash/development_workflow.rst index dac7034b279a..78f2bd6f86e0 100644 --- a/doc/devel/gitwash/development_workflow.rst +++ b/doc/devel/gitwash/development_workflow.rst @@ -52,17 +52,17 @@ use:: git fetch origin git checkout -b my-new-feature origin/v1.0.x -Generally, you will want to keep this also on your public github_ fork -of matplotlib_. To do this, you `git push`_ this new branch up to your github_ +Generally, you will want to keep this also on your public GitHub_ fork +of matplotlib_. To do this, you `git push`_ this new branch up to your GitHub_ repo. Generally (if you followed the instructions in these pages, and -by default), git will have a link to your github_ repo, called -``origin``. You push up to your own repo on github_ with:: +by default), git will have a link to your GitHub_ repo, called +``origin``. You push up to your own repo on GitHub_ with:: git push origin my-new-feature You will need to use this exact command, rather than simply ``git push`` every time you want to push changes on your feature branch to -your github_ repo. However, in git >1.7 you can set up a link by +your GitHub_ repo. However, in git >1.7 you can set up a link by using the ``--set-upstream`` option:: git push --set-upstream origin my-new-feature @@ -114,7 +114,7 @@ In more detail faith |emdash| or see `why the -a flag?`_ |emdash| and the helpful use-case description in the `tangled working copy problem`_. The `git commit`_ manual page might also be useful. -#. To push the changes up to your forked repo on github_, do a ``git +#. To push the changes up to your forked repo on GitHub_, do a ``git push`` (see `git push`). Asking for code review |emdash| open a Pull Request (PR) @@ -153,7 +153,7 @@ 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 +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. @@ -166,8 +166,8 @@ explanation (with pictures!) see `this nice write up 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 +The following example assumes that the remote of _your_ GitHub +repository is called `origin` 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 @@ -269,13 +269,13 @@ 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 +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 + $ git push --force origin -which will _replace_ all of the commits under your branch on 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! @@ -283,7 +283,7 @@ Congratulations, you have rebased your branch! Staying up to date with changes in the central repository ========================================================= -This updates your working copy from the upstream `matplotlib github`_ +This updates your working copy from the upstream `matplotlib GitHub`_ repo. Overview @@ -294,9 +294,9 @@ Overview # go to your master branch git checkout master # pull changes from github - git fetch upstream - # merge from upstream - git merge --ff-only upstream/master + git fetch matplotlib + # merge from matplotlib + git merge --ff-only matplotlib/master In detail --------- @@ -334,7 +334,7 @@ Other integration branches -------------------------- Some people like to keep separate local branches corresponding to the -maintenance branches on github. At the time of this writing, ``v1.0.x`` +maintenance branches on GitHub. At the time of this writing, ``v1.0.x`` is the active maintenance branch. If you have such a local branch, treat is just as ``master``: don't commit on it, and before starting new branches off of it, update it from upstream:: @@ -383,7 +383,7 @@ make sure to reset the correct branch:: git reset --hard upstream/master -Deleting a branch on github_ +Deleting a branch on GitHub_ ============================ :: @@ -391,12 +391,44 @@ Deleting a branch on github_ git checkout master # delete branch locally git branch -D my-unwanted-branch - # delete branch on github + # delete branch on GitHub git push origin :my-unwanted-branch (Note the colon ``:`` before ``test-branch``. See also: http://github.com/guides/remove-a-remote-branch +<<<<<<< b3d268fa14cd1d19ac7ce337425602944b6e52b3 +======= +Several people sharing a single repository +========================================== + +If you want to work on some stuff with other people, where you are all +committing into the same repository, or even the same branch, then just +share it via GitHub_. + +First fork matplotlib into your account, as from :ref:`forking`. + +Then, go to your forked repository GitHub page, say +``http://github.com/your-user-name/matplotlib`` + +Click on the 'Admin' button, and add anyone else to the repo as a +collaborator: + + .. image:: pull_button.png + +Now all those people can do:: + + git clone git@github.com:your-user-name/matplotlib.git + +Remember that links starting with ``git@`` use the ssh protocol and are +read-write; links starting with ``git://`` are read-only. + +Your collaborators can then commit directly into that repo with the +usual:: + + git commit -am 'ENH - much better code' + git push origin master # pushes directly into your repo +>>>>>>> FIX github -> GitHub Exploring your repository ========================= @@ -410,7 +442,7 @@ To see a linear list of commits for this branch:: git log -You can also look at the `network graph visualizer`_ for your github_ +You can also look at the `network graph visualizer`_ for your GitHub_ repo. .. include:: links.inc From 2ffb590cbaa95e54c4e77b94670ff0be55abd185 Mon Sep 17 00:00:00 2001 From: Nelle Varoquaux Date: Wed, 14 Sep 2016 22:12:33 -0700 Subject: [PATCH 08/10] =?UTF-8?q?FIX=20nitpicks=E2=80=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/devel/gitwash/development_workflow.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/devel/gitwash/development_workflow.rst b/doc/devel/gitwash/development_workflow.rst index 78f2bd6f86e0..cb5c5c0db75a 100644 --- a/doc/devel/gitwash/development_workflow.rst +++ b/doc/devel/gitwash/development_workflow.rst @@ -160,7 +160,7 @@ 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 +`. The NumPy team has also `documented how to do this ` In general, re-writing history, particularly published history, is considered @@ -207,9 +207,9 @@ and git will then give a bunch of feed back:: 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 :: +the tip of `matplotlib/master`. However, git may eventually hit a commit +that had conflicts: in the example above, this happens in the file +`lib/matplotlib/backends/backend_gtk3.py`). For more verbose information run :: $ git status From 92f4006abc397c9131b0712aa425e07025390a9f Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Thu, 15 Sep 2016 23:43:52 -0400 Subject: [PATCH 09/10] DOC: remove merge conflict --- doc/devel/gitwash/development_workflow.rst | 32 ---------------------- 1 file changed, 32 deletions(-) diff --git a/doc/devel/gitwash/development_workflow.rst b/doc/devel/gitwash/development_workflow.rst index cb5c5c0db75a..9778bd42a74c 100644 --- a/doc/devel/gitwash/development_workflow.rst +++ b/doc/devel/gitwash/development_workflow.rst @@ -397,38 +397,6 @@ Deleting a branch on GitHub_ (Note the colon ``:`` before ``test-branch``. See also: http://github.com/guides/remove-a-remote-branch -<<<<<<< b3d268fa14cd1d19ac7ce337425602944b6e52b3 -======= -Several people sharing a single repository -========================================== - -If you want to work on some stuff with other people, where you are all -committing into the same repository, or even the same branch, then just -share it via GitHub_. - -First fork matplotlib into your account, as from :ref:`forking`. - -Then, go to your forked repository GitHub page, say -``http://github.com/your-user-name/matplotlib`` - -Click on the 'Admin' button, and add anyone else to the repo as a -collaborator: - - .. image:: pull_button.png - -Now all those people can do:: - - git clone git@github.com:your-user-name/matplotlib.git - -Remember that links starting with ``git@`` use the ssh protocol and are -read-write; links starting with ``git://`` are read-only. - -Your collaborators can then commit directly into that repo with the -usual:: - - git commit -am 'ENH - much better code' - git push origin master # pushes directly into your repo ->>>>>>> FIX github -> GitHub Exploring your repository ========================= From 9efe5e36b57bf11fb2bfd7e9229c06656fd10bff Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Thu, 15 Sep 2016 23:48:10 -0400 Subject: [PATCH 10/10] DOC: minor wording changes --- doc/devel/gitwash/development_workflow.rst | 27 ++++++++++++---------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/doc/devel/gitwash/development_workflow.rst b/doc/devel/gitwash/development_workflow.rst index 9778bd42a74c..aed61d7e980a 100644 --- a/doc/devel/gitwash/development_workflow.rst +++ b/doc/devel/gitwash/development_workflow.rst @@ -150,7 +150,7 @@ 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 +the top of `CHANGELOG`. Git can not unambiguously tell what to do 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 @@ -206,10 +206,11 @@ and git will then give a bunch of feed back:: 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 may eventually hit a commit -that had conflicts: in the example above, this happens in the file -`lib/matplotlib/backends/backend_gtk3.py`). For more verbose information run :: +We see that a number of commits could be cleanly applied to the tip of +`matplotlib/master`. However, git may eventually hit a commit that +had conflicts: in the example above, this happens in the file +`lib/matplotlib/backends/backend_gtk3.py`). For more verbose +information run :: $ git status @@ -226,9 +227,10 @@ that had conflicts: in the example above, this happens in the file 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:: +This tells you exactly where the conflict (caused by the target branch +and your commits modifying the same lines of code) 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 ======= @@ -237,10 +239,11 @@ blocks that look something like this:: 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:: +and `>>>>>>>` is the code in the commit you are trying to rebase. The +rest of the code is either the same or the diff can be unambiguously +applied. 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