##// END OF EJS Templates
DOC: Fix typo in a recommended command in gitwash.
Robert Kern -
Show More
@@ -1,233 +1,233 b''
1 1 .. _development-workflow:
2 2
3 3 ====================
4 4 Development workflow
5 5 ====================
6 6
7 7 You already have your own forked copy of the ipython_ repository, by
8 8 following :ref:`forking`, :ref:`set-up-fork`, and you have configured
9 9 git_ by following :ref:`configure-git`.
10 10
11 11 Workflow summary
12 12 ================
13 13
14 14 * Keep your ``master`` branch clean of edits that have not been merged
15 15 to the main ipython_ development repo. Your ``master`` then will follow
16 16 the main ipython_ repository.
17 17 * Start a new *feature branch* for each set of edits that you do.
18 18 * If you can avoid it, try not to merge other branches into your feature
19 19 branch while you are working.
20 20 * Ask for review!
21 21
22 22 This way of working really helps to keep work well organized, and in
23 23 keeping history as clear as possible.
24 24
25 25 See - for example - `linux git workflow`_.
26 26
27 27 Making a new feature branch
28 28 ===========================
29 29
30 30 ::
31 31
32 32 git branch my-new-feature
33 33 git checkout my-new-feature
34 34
35 35 Generally, you will want to keep this also on your public github_ fork
36 36 of ipython_. To do this, you `git push`_ this new branch up to your github_
37 37 repo. Generally (if you followed the instructions in these pages, and
38 38 by default), git will have a link to your github_ repo, called
39 39 ``origin``. You push up to your own repo on github_ with::
40 40
41 41 git push origin my-new-feature
42 42
43 43 From now on git_ will know that ``my-new-feature`` is related to the
44 44 ``my-new-feature`` branch in the github_ repo.
45 45
46 46 The editing workflow
47 47 ====================
48 48
49 49 Overview
50 50 --------
51 51
52 52 ::
53 53
54 54 # hack hack
55 55 git add my_new_file
56 56 git commit -am 'NF - some message'
57 57 git push
58 58
59 59 In more detail
60 60 --------------
61 61
62 62 #. Make some changes
63 63 #. See which files have changed with ``git status`` (see `git status`_).
64 64 You'll see a listing like this one::
65 65
66 66 # On branch ny-new-feature
67 67 # Changed but not updated:
68 68 # (use "git add <file>..." to update what will be committed)
69 69 # (use "git checkout -- <file>..." to discard changes in working directory)
70 70 #
71 71 # modified: README
72 72 #
73 73 # Untracked files:
74 74 # (use "git add <file>..." to include in what will be committed)
75 75 #
76 76 # INSTALL
77 77 no changes added to commit (use "git add" and/or "git commit -a")
78 78
79 79 #. Check what the actual changes are with ``git diff`` (`git diff`_).
80 80 #. Add any new files to version control ``git add new_file_name`` (see
81 81 `git add`_).
82 82 #. To commit all modified files into the local copy of your repo,, do
83 83 ``git commit -am 'A commit message'``. Note the ``-am`` options to
84 84 ``commit``. The ``m`` flag just signals that you're going to type a
85 85 message on the command line. The ``a`` flag - you can just take on
86 86 faith - or see `why the -a flag?`_. See also the `git commit`_ manual
87 87 page.
88 88 #. To push the changes up to your forked repo on github_, do a ``git
89 89 push`` (see `git push`).
90 90
91 91 Asking for code review
92 92 ======================
93 93
94 94 #. Go to your repo URL - e.g. ``http://github.com/your-user-name/ipython``.
95 95 #. Click on the *Branch list* button:
96 96
97 97 .. image:: branch_list.png
98 98
99 99 #. Click on the *Compare* button for your feature branch - here ``my-new-feature``:
100 100
101 101 .. image:: branch_list_compare.png
102 102
103 103 #. If asked, select the *base* and *comparison* branch names you want to
104 104 compare. Usually these will be ``master`` and ``my-new-feature``
105 105 (where that is your feature branch name).
106 106 #. At this point you should get a nice summary of the changes. Copy the
107 107 URL for this, and post it to the `ipython mailing list`_, asking for
108 108 review. The URL will look something like:
109 109 ``http://github.com/your-user-name/ipython/compare/master...my-new-feature``.
110 110 There's an example at
111 111 http://github.com/matthew-brett/nipy/compare/master...find-install-data
112 112 See: http://github.com/blog/612-introducing-github-compare-view for
113 113 more detail.
114 114
115 115 The generated comparison, is between your feature branch
116 116 ``my-new-feature``, and the place in ``master`` from which you branched
117 117 ``my-new-feature``. In other words, you can keep updating ``master``
118 118 without interfering with the output from the comparison. More detail?
119 119 Note the three dots in the URL above (``master...my-new-feature``) and
120 120 see :ref:`dot2-dot3`.
121 121
122 122 Asking for your changes to be merged with the main repo
123 123 =======================================================
124 124
125 125 When you are ready to ask for the merge of your code:
126 126
127 127 #. Go to the URL of your forked repo, say
128 128 ``http://github.com/your-user-name/ipython.git``.
129 129 #. Click on the 'Pull request' button:
130 130
131 131 .. image:: pull_button.png
132 132
133 133 Enter a message; we suggest you select only ``ipython`` as the
134 134 recipient. The message will go to the `ipython mailing list`_. Please
135 135 feel free to add others from the list as you like.
136 136
137 137 Merging from trunk
138 138 ==================
139 139
140 140 This updates your code from the upstream `ipython github`_ repo.
141 141
142 142 Overview
143 143 --------
144 144
145 145 ::
146 146
147 147 # go to your master branch
148 148 git checkout master
149 149 # pull changes from github
150 150 git fetch upstream
151 151 # merge from upstream
152 git merge upstream master
152 git merge upstream/master
153 153
154 154 In detail
155 155 ---------
156 156
157 157 We suggest that you do this only for your ``master`` branch, and leave
158 158 your 'feature' branches unmerged, to keep their history as clean as
159 159 possible. This makes code review easier::
160 160
161 161 git checkout master
162 162
163 163 Make sure you have done :ref:`linking-to-upstream`.
164 164
165 165 Merge the upstream code into your current development by first pulling
166 166 the upstream repo to a copy on your local machine::
167 167
168 168 git fetch upstream
169 169
170 170 then merging into your current branch::
171 171
172 172 git merge upstream/master
173 173
174 174 Deleting a branch on github_
175 175 ============================
176 176
177 177 ::
178 178
179 179 git checkout master
180 180 # delete branch locally
181 181 git branch -D my-unwanted-branch
182 182 # delete branch on github
183 183 git push origin :my-unwanted-branch
184 184
185 185 (Note the colon ``:`` before ``test-branch``. See also:
186 186 http://github.com/guides/remove-a-remote-branch
187 187
188 188 Several people sharing a single repository
189 189 ==========================================
190 190
191 191 If you want to work on some stuff with other people, where you are all
192 192 committing into the same repository, or even the same branch, then just
193 193 share it via github_.
194 194
195 195 First fork ipython into your account, as from :ref:`forking`.
196 196
197 197 Then, go to your forked repository github page, say
198 198 ``http://github.com/your-user-name/ipython``
199 199
200 200 Click on the 'Admin' button, and add anyone else to the repo as a
201 201 collaborator:
202 202
203 203 .. image:: pull_button.png
204 204
205 205 Now all those people can do::
206 206
207 207 git clone git@githhub.com:your-user-name/ipython.git
208 208
209 209 Remember that links starting with ``git@`` use the ssh protocol and are
210 210 read-write; links starting with ``git://`` are read-only.
211 211
212 212 Your collaborators can then commit directly into that repo with the
213 213 usual::
214 214
215 215 git commit -am 'ENH - much better code'
216 216 git push origin master # pushes directly into your repo
217 217
218 218 Exploring your repository
219 219 =========================
220 220
221 221 To see a graphical representation of the repository branches and
222 222 commits::
223 223
224 224 gitk --all
225 225
226 226 To see a linear list of commits for this branch::
227 227
228 228 git log
229 229
230 230 You can also look at the `network graph visualizer`_ for your github_
231 231 repo.
232 232
233 233 .. include:: git_links.txt
General Comments 0
You need to be logged in to leave comments. Login now