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