1.. highlight:: bash 2 3================ 4 Making a patch 5================ 6 7You've discovered a bug or something else you want to change 8in `Matplotlib`_ .. |emdash| excellent! 9 10You've worked out a way to fix it |emdash| even better! 11 12You want to tell us about it |emdash| best of all! 13 14The easiest way is to make a *patch* or set of patches. Here 15we explain how. Making a patch is the simplest and quickest, 16but if you're going to be doing anything more than simple 17quick things, please consider following the 18:ref:`git-development` model instead. 19 20.. _making-patches: 21 22Making patches 23============== 24 25Overview 26-------- 27 28:: 29 30 # tell git who you are 31 git config --global user.email you@yourdomain.example.com 32 git config --global user.name "Your Name Comes Here" 33 # get the repository if you don't have it 34 git clone git://github.com/matplotlib/matplotlib.git 35 # make a branch for your patching 36 cd matplotlib 37 git branch the-fix-im-thinking-of 38 git checkout the-fix-im-thinking-of 39 # hack, hack, hack 40 # Tell git about any new files you've made 41 git add somewhere/tests/test_my_bug.py 42 # commit work in progress as you go 43 git commit -am 'BF - added tests for Funny bug' 44 # hack hack, hack 45 git commit -am 'BF - added fix for Funny bug' 46 # make the patch files 47 git format-patch -M -C master 48 49Then, send the generated patch files to the `Matplotlib 50mailing list`_ |emdash| where we will thank you warmly. 51 52In detail 53--------- 54 55#. Tell git who you are so it can label the commits you've 56 made:: 57 58 git config --global user.email you@yourdomain.example.com 59 git config --global user.name "Your Name Comes Here" 60 61#. If you don't already have one, clone a copy of the 62 `Matplotlib`_ repository:: 63 64 git clone git://github.com/matplotlib/matplotlib.git 65 cd matplotlib 66 67#. Make a 'feature branch'. This will be where you work on 68 your bug fix. It's nice and safe and leaves you with 69 access to an unmodified copy of the code in the main 70 branch:: 71 72 git branch the-fix-im-thinking-of 73 git checkout the-fix-im-thinking-of 74 75#. Do some edits, and commit them as you go:: 76 77 # hack, hack, hack 78 # Tell git about any new files you've made 79 git add somewhere/tests/test_my_bug.py 80 # commit work in progress as you go 81 git commit -am 'BF - added tests for Funny bug' 82 # hack hack, hack 83 git commit -am 'BF - added fix for Funny bug' 84 85 Note the ``-am`` options to ``commit``. The ``m`` flag just 86 signals that you're going to type a message on the command 87 line. The ``a`` flag |emdash| you can just take on faith |emdash| 88 or see `why the -a flag?`_. 89 90#. When you have finished, check you have committed all your 91 changes:: 92 93 git status 94 95#. Finally, make your commits into patches. You want all the 96 commits since you branched from the ``master`` branch:: 97 98 git format-patch -M -C master 99 100 You will now have several files named for the commits: 101 102 .. code-block:: none 103 104 0001-BF-added-tests-for-Funny-bug.patch 105 0002-BF-added-fix-for-Funny-bug.patch 106 107 Send these files to the `Matplotlib mailing list`_. 108 109When you are done, to switch back to the main copy of the 110code, just return to the ``master`` branch:: 111 112 git checkout master 113 114Moving from patching to development 115=================================== 116 117If you find you have done some patches, and you have one or 118more feature branches, you will probably want to switch to 119development mode. You can do this with the repository you 120have. 121 122Fork the `Matplotlib`_ repository on github |emdash| :ref:`forking`. 123Then:: 124 125 # checkout and refresh master branch from main repo 126 git checkout master 127 git pull origin master 128 # rename pointer to main repository to 'upstream' 129 git remote rename origin upstream 130 # point your repo to default read / write to your fork on github 131 git remote add origin git@github.com:your-user-name/matplotlib.git 132 # push up any branches you've made and want to keep 133 git push origin the-fix-im-thinking-of 134 135Then you can, if you want, follow the 136:ref:`development-workflow`. 137 138.. include:: links.inc 139