Statistics
| Branch: | Revision:

iof-tools / networkxMiCe / networkx-master / doc / developer / gitwash / patching.rst @ 5cef0f13

History | View | Annotate | Download (4 KB)

1
.. highlight:: bash
2

    
3
================
4
 Making a patch
5
================
6

    
7
You've discovered a bug or something else you want to change
8
in `networkx`_ .. |emdash| excellent!
9

    
10
You've worked out a way to fix it |emdash| even better!
11

    
12
You want to tell us about it |emdash| best of all!
13

    
14
The easiest way is to make a *patch* or set of patches.  Here
15
we explain how.  Making a patch is the simplest and quickest,
16
but if you're going to be doing anything more than simple
17
quick things, please consider following the
18
:ref:`git-development` model instead.
19

    
20
.. _making-patches:
21

    
22
Making patches
23
==============
24

    
25
Overview
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/networkx/networkx.git
35
   # make a branch for your patching
36
   cd networkx
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

    
49
Then, send the generated patch files to the `networkx
50
mailing list`_ |emdash| where we will thank you warmly.
51

    
52
In 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
   `networkx`_ repository::
63

    
64
      git clone git://github.com/networkx/networkx.git
65
      cd networkx
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 `networkx mailing list`_.
108

    
109
When you are done, to switch back to the main copy of the
110
code, just return to the ``master`` branch::
111

    
112
   git checkout master
113

    
114
Moving from patching to development
115
===================================
116

    
117
If you find you have done some patches, and you have one or
118
more feature branches, you will probably want to switch to
119
development mode.  You can do this with the repository you
120
have.
121

    
122
Fork the `networkx`_ repository on github |emdash| :ref:`forking`.
123
Then::
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/networkx.git
132
   # push up any branches you've made and want to keep
133
   git push origin the-fix-im-thinking-of
134

    
135
Then you can, if you want, follow the
136
:ref:`development-workflow`.
137

    
138
.. include:: links.inc