From bada3ca95f0a924aa6f96c54baeff76c446610c1 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Mon, 5 Mar 2018 11:24:16 +0100 Subject: [PATCH 1/3] DOC: update contributing guide regarding updating a pull request (merge master) --- doc/source/contributing.rst | 62 +++++++++++++++++++------------------ 1 file changed, 32 insertions(+), 30 deletions(-) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index e159af9958fde..affb55f863336 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -964,32 +964,6 @@ Now you can commit your changes in your local repository:: git commit -m -Combining commits ------------------ - -If you have multiple commits, you may want to combine them into one commit, often -referred to as "squashing" or "rebasing". This is a common request by package maintainers -when submitting a pull request as it maintains a more compact commit history. To rebase -your commits:: - - git rebase -i HEAD~# - -Where # is the number of commits you want to combine. Then you can pick the relevant -commit message and discard others. - -To squash to the master branch do:: - - git rebase -i master - -Use the ``s`` option on a commit to ``squash``, meaning to keep the commit messages, -or ``f`` to ``fixup``, meaning to merge the commit messages. - -Then you will need to push the branch (see below) forcefully to replace the current -commits with the new ones:: - - git push origin shiny-new-feature -f - - Pushing your changes -------------------- @@ -1045,15 +1019,43 @@ release. To submit a pull request: #. Click ``Send Pull Request``. This request then goes to the repository maintainers, and they will review -the code. If you need to make more changes, you can make them in -your branch, push them to GitHub, and the pull request will be automatically -updated. Pushing them to GitHub again is done by:: +the code. + +Updating your pull request +-------------------------- - git push -f origin shiny-new-feature +Based on the review you get on your pull request, you will probably need to make +some changes to the code. In that case, you can make them in your branch, +add a new commit to that branch, push it to GitHub, and the pull request will be +automatically updated. Pushing them to GitHub again is done by:: + + git push origin shiny-new-feature This will automatically update your pull request with the latest code and restart the :ref:`Continuous Integration ` tests. +Another reason you might need to update your pull request is to solve conflicts +with changes that have been merged into the master branch since you opened your +pull request. + +To do this, you need to "merge upstream master" in your branch:: + + git checkout shiny-new-feature + git fetch upstream + git merge upstream/master + +If there are no conflicts (or they could be fixed automatically), a file with a +default commit message will open, and you can simply save and quit this file. + +If there are merge conflicts, you need to solve those conflicts. See for +example at https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/ +for an explanation on how to do this. +Once the conflicts are merged and the files where the conflicts were solved are +added, you can run ``git commit`` to save those fixes. + +Now you can update your pull request by pushing to the branch on GitHub:: + + git push origin shiny-new-feature Delete your merged branch (optional) ------------------------------------ From f24deb4df069b800b8f51a5631ec61bfaadec9d4 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 8 Mar 2018 11:30:16 +0100 Subject: [PATCH 2/3] remove rebasing for updating branch + add pull for updating master --- doc/source/contributing.rst | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index affb55f863336..f899710158821 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -246,16 +246,16 @@ changes in this branch specific to one bug or feature so it is clear what the branch brings to *pandas*. You can have many shiny-new-features and switch in between them using the git checkout command. -To update this branch, you need to retrieve the changes from the master branch:: +When creating this branch, make sure your master branch is up to date with +the latest upstream master version. To update your local master branch, you +can do:: - git fetch upstream - git rebase upstream/master + git checkout master + git pull upstream master --ff-only -This will replay your commits on top of the latest pandas git master. If this -leads to merge conflicts, you must resolve these before submitting your pull -request. If you have uncommitted changes, you will need to ``stash`` them prior -to updating. This will effectively store your changes and they can be reapplied -after updating. +When you want to update the feature branch with changes in master after +you created the branch, check the section on +:ref:`updating a PR `. .. _contributing.documentation: @@ -1021,6 +1021,8 @@ release. To submit a pull request: This request then goes to the repository maintainers, and they will review the code. +.. _contributing.update-pr: + Updating your pull request -------------------------- @@ -1053,7 +1055,12 @@ for an explanation on how to do this. Once the conflicts are merged and the files where the conflicts were solved are added, you can run ``git commit`` to save those fixes. -Now you can update your pull request by pushing to the branch on GitHub:: +If you have uncommitted changes at the moment you want to update the branch with +master, you will need to ``stash`` them prior to updating. This will effectively +store your changes and they can be reapplied after updating. + +After the feature branch has been update locally, you can now update your pull +request by pushing to the branch on GitHub:: git push origin shiny-new-feature From c5b04756712d7999c597f392d5bd004b5733d5b3 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 15 Mar 2018 15:03:54 +0100 Subject: [PATCH 3/3] add link about stashing --- doc/source/contributing.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 9ec6b7392b135..f7fc9575566b7 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -1056,8 +1056,9 @@ Once the conflicts are merged and the files where the conflicts were solved are added, you can run ``git commit`` to save those fixes. If you have uncommitted changes at the moment you want to update the branch with -master, you will need to ``stash`` them prior to updating. This will effectively -store your changes and they can be reapplied after updating. +master, you will need to ``stash`` them prior to updating (see the +`stash docs `__). +This will effectively store your changes and they can be reapplied after updating. After the feature branch has been update locally, you can now update your pull request by pushing to the branch on GitHub::