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