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 |
|
|
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