From 586baec91934f01c82f5f4fda29b9ad55ab5120d Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Sat, 26 Feb 2011 08:17:54 -0500 Subject: [PATCH 1/4] Add some clarifications and comments to the gitwash instructions based on my newbie experience. --- doc/devel/gitwash/development_workflow.rst | 37 +++++++++++++++++----- doc/devel/gitwash/set_up_fork.rst | 13 +++++--- 2 files changed, 38 insertions(+), 12 deletions(-) diff --git a/doc/devel/gitwash/development_workflow.rst b/doc/devel/gitwash/development_workflow.rst index c392f8b4b9dd..269ff81ef775 100644 --- a/doc/devel/gitwash/development_workflow.rst +++ b/doc/devel/gitwash/development_workflow.rst @@ -32,6 +32,12 @@ Making a new feature branch git branch my-new-feature git checkout my-new-feature +This will create a feature branch based on ``master``. To create a +feature branch based on a maintenance branch, use:: + + git branch my-new-feature remotes/origin/v1.0.x + git checkout my-new-feature + 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 @@ -40,13 +46,15 @@ by default), git will have a link to your github_ repo, called git push origin my-new-feature -In git >1.7 you can ensure that the link is correctly set by using the -``--set-upstream`` option:: +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 +using the ``--set-upstream`` option:: git push --set-upstream origin my-new-feature -From now on git_ will know that ``my-new-feature`` is related to the -``my-new-feature`` branch in the github_ repo. +and then next time you need to push changes to your branch a simple +``git push`` will suffice. The editing workflow ==================== @@ -125,7 +133,7 @@ without interfering with the output from the comparison. More detail? Note the three dots in the URL above (``master...my-new-feature``) and see :ref:`dot2-dot3`. -Asking for your changes to be merged with the main repo +Asking for your changes to be merged into the main repo ======================================================= When you are ready to ask for the merge of your code: @@ -140,10 +148,15 @@ When you are ready to ask for the merge of your code: recipient. The message will go to the `matplotlib mailing list`_. Please feel free to add others from the list as you like. -Merging from trunk -================== +#. If the branch is to be merged into a maintenance branch on the main + repo, make sure the "base branch" indicates the maintenance branch + and not master. -This updates your code from the upstream `matplotlib github`_ repo. +Staying up to date with changes in the central repository +========================================================= + +This updates your working copy from the upstream `matplotlib github`_ +repo. Overview -------- @@ -177,6 +190,14 @@ then merging into your current branch:: git merge upstream/master +.. Doesn't one then need to push this up to the private repository? I +.. have multiple machines I use for development, and I don't want to +.. have to do this on all of them - MGD + +.. Does this need to be done for each maintenance branch as well? +.. This doesn't seem to be sufficient to pull in changes on an +.. upstream maintenance branch. - MGD + Deleting a branch on github_ ============================ diff --git a/doc/devel/gitwash/set_up_fork.rst b/doc/devel/gitwash/set_up_fork.rst index cf4d77e258f6..0ebc5f32ced6 100644 --- a/doc/devel/gitwash/set_up_fork.rst +++ b/doc/devel/gitwash/set_up_fork.rst @@ -56,12 +56,17 @@ Note that we've used ``git://`` for the URL rather than ``git@``. The (or deliberately) write to the upstream repo, and we are only going to use it to merge into our own code. +Note this command needs to be run on every clone of the repository +that you make. It is not tracked in your personal repository on +github_. + Just for your own satisfaction, show yourself that you now have a new 'remote', with ``git remote -v show``, giving you something like:: - upstream git://github.com/matplotlib/matplotlib.git (fetch) - upstream git://github.com/matplotlib/matplotlib.git (push) - origin git@github.com:your-user-name/matplotlib.git (fetch) - origin git@github.com:your-user-name/matplotlib.git (push) + upstream git://github.com/matplotlib/matplotlib.git (fetch) + upstream git://github.com/matplotlib/matplotlib.git (push) + origin git@github.com:your-user-name/matplotlib.git (fetch) + origin git@github.com:your-user-name/matplotlib.git (push) .. include:: links.inc + From 649fcdde9e0a9c8160eb7c4ae52840c63822845b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jouni=20K=2E=20Sepp=C3=A4nen?= Date: Fri, 11 Mar 2011 10:22:40 +0200 Subject: [PATCH 2/4] Further gitwash clarifications --- doc/devel/gitwash/development_workflow.rst | 88 +++++++++++++++++++--- 1 file changed, 79 insertions(+), 9 deletions(-) diff --git a/doc/devel/gitwash/development_workflow.rst b/doc/devel/gitwash/development_workflow.rst index 269ff81ef775..21d4e451eec7 100644 --- a/doc/devel/gitwash/development_workflow.rst +++ b/doc/devel/gitwash/development_workflow.rst @@ -29,14 +29,14 @@ Making a new feature branch :: - git branch my-new-feature - git checkout my-new-feature + git checkout -b my-new-feature master -This will create a feature branch based on ``master``. To create a -feature branch based on a maintenance branch, use:: +This will create and immediately check out a feature branch based on +``master``. To create a feature branch based on a maintenance branch, +use:: - git branch my-new-feature remotes/origin/v1.0.x - git checkout my-new-feature + 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_ @@ -54,7 +54,8 @@ using the ``--set-upstream`` option:: git push --set-upstream origin my-new-feature and then next time you need to push changes to your branch a simple -``git push`` will suffice. +``git push`` will suffice. Note that ``git push`` pushes out all +branches that are linked to a remote branch. The editing workflow ==================== @@ -168,7 +169,7 @@ Overview # pull changes from github git fetch upstream # merge from upstream - git merge upstream/master + git merge --ff-only upstream/master In detail --------- @@ -188,16 +189,85 @@ the upstream repo to a copy on your local machine:: then merging into your current branch:: - git merge upstream/master + git merge --ff-only upstream/master + +The ``--ff-only`` option guarantees that if you have mistakenly +committed code on your ``master`` branch, the merge fails at this point. +If you were to merge ``upstream/master`` to your ``master``, you +would start to diverge from the upstream. If this command fails, see +the section on accidents_. .. Doesn't one then need to push this up to the private repository? I .. have multiple machines I use for development, and I don't want to .. have to do this on all of them - MGD +.. Not really; does the paragraph below explain this enough? - JKS + +The letters 'ff' in ``--ff-only`` mean 'fast forward', which is a +special case of merge where git can simply update your branch to point +to the other branch and not do any actual merging of files. For +``master`` and other integration branches this is exactly what you +want. + .. Does this need to be done for each maintenance branch as well? .. This doesn't seem to be sufficient to pull in changes on an .. upstream maintenance branch. - MGD +.. Does the section below answer this? - JKS + +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`` +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:: + + git checkout v1.0.x + git fetch upstream + git merge --ff-only upstream/v1.0.x + +But you don't necessarily have to have such a branch. Instead, if you +are preparing a bugfix that applies to the maintenance branch, fetch +from upstream and base your bugfix on the remote branch;: + + git fetch upstream + git checkout -b my-bug-fix upstream/v1.0.x + +.. _accidents: + +Recovering from accidental commits on master +-------------------------------------------- + +If you have accidentally committed changes on ``master`` and +``git merge --ff-only`` fails, don't panic! First find out how much +you have diverged:: + + git diff upstream/master...master + +If you find that you want simply to get rid of the changes, reset +your ``master`` branch to the upstream version:: + + git reset --hard upstream/master + +As you might surmise from the words 'reset' and 'hard', this command +actually causes your changes to the current branch to be lost, so +think twice. + +If, on the other hand, you find that you want to preserve the changes, +create a feature branch for them:: + + git checkout -b my-important-changes + +Now ``my-important-changes`` points to the branch that has your +changes, and you can safely reset ``master`` as above |emdash| but +make sure to reset the correct branch:: + + git checkout master + git reset --hard upstream/master + + Deleting a branch on github_ ============================ From 13419cc66a443c83341f2da76793de58ebdb89bd Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Mon, 4 Apr 2011 08:21:13 -0400 Subject: [PATCH 3/4] Fix minor typo --- doc/devel/gitwash/development_workflow.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/devel/gitwash/development_workflow.rst b/doc/devel/gitwash/development_workflow.rst index 21d4e451eec7..31bd02599011 100644 --- a/doc/devel/gitwash/development_workflow.rst +++ b/doc/devel/gitwash/development_workflow.rst @@ -230,7 +230,7 @@ new branches off of it, update it from upstream:: But you don't necessarily have to have such a branch. Instead, if you are preparing a bugfix that applies to the maintenance branch, fetch -from upstream and base your bugfix on the remote branch;: +from upstream and base your bugfix on the remote branch:: git fetch upstream git checkout -b my-bug-fix upstream/v1.0.x From 4b7f4b862b59596b4e570bc1a124c39bf264e030 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Mon, 4 Apr 2011 08:26:10 -0400 Subject: [PATCH 4/4] Minor fixes based on comments in the thread. --- doc/devel/gitwash/development_workflow.rst | 19 ++++--------------- 1 file changed, 4 insertions(+), 15 deletions(-) diff --git a/doc/devel/gitwash/development_workflow.rst b/doc/devel/gitwash/development_workflow.rst index 31bd02599011..ef2429082a3a 100644 --- a/doc/devel/gitwash/development_workflow.rst +++ b/doc/devel/gitwash/development_workflow.rst @@ -82,12 +82,12 @@ In more detail # (use "git add ..." to update what will be committed) # (use "git checkout -- ..." to discard changes in working directory) # - # modified: README + # modified: README # # Untracked files: # (use "git add ..." to include in what will be committed) # - # INSTALL + # INSTALL no changes added to commit (use "git add" and/or "git commit -a") #. Check what the actual changes are with ``git diff`` (`git diff`_). @@ -151,7 +151,8 @@ When you are ready to ask for the merge of your code: #. If the branch is to be merged into a maintenance branch on the main repo, make sure the "base branch" indicates the maintenance branch - and not master. + and not master. Github can not automatically determine the branch + to merge into. Staying up to date with changes in the central repository ========================================================= @@ -197,24 +198,12 @@ If you were to merge ``upstream/master`` to your ``master``, you would start to diverge from the upstream. If this command fails, see the section on accidents_. -.. Doesn't one then need to push this up to the private repository? I -.. have multiple machines I use for development, and I don't want to -.. have to do this on all of them - MGD - -.. Not really; does the paragraph below explain this enough? - JKS - The letters 'ff' in ``--ff-only`` mean 'fast forward', which is a special case of merge where git can simply update your branch to point to the other branch and not do any actual merging of files. For ``master`` and other integration branches this is exactly what you want. -.. Does this need to be done for each maintenance branch as well? -.. This doesn't seem to be sufficient to pull in changes on an -.. upstream maintenance branch. - MGD - -.. Does the section below answer this? - JKS - Other integration branches --------------------------