Rename source/ => doc/
[ryppl:doc.git] / doc / modifying_the_python_lib.rst
1 .. highlight:: git_shell
2
3 Scenario:  I want to work on a library
4 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5
6 We want to make modifications to project boost.python, with the
7 intention of eventually making a merge request to the project's owner.
8
9 .. warning:: Do these steps in order!!!
10
11
12 .. I think this is an abuse of “rubric.”  Google “define:rubric” to
13 .. see what I mean.  These should be regular sections, or ordered
14 .. lists, or something.
15
16 .. rubric:: Clone the Boost superproject on Gitorious
17
18
19 .. I cleaned up the below as best I could, but you need to get rid of
20 .. spurious clones on Gitorious before I really know what to do with
21 .. it.  Please do that and check the paragraph over to make sure it
22 .. makes sense.
23
24 Make a clone of boost on gitorious, using the "Clone this repository
25 on gitorious" link on `ryppl's gitorious page
26 <http://gitorious.org/ryppl/boost>`_.  Later this will contain a
27 modified submodule pointing to our clone of python, which we will
28 create later.  The other Boost library submodules will continue to
29 refer to their standard “official” locations.  I have called mine
30 *straszheims-ryppl*, here:
31 http://gitorious.org/~straszheim/ryppl/straszheims-ryppl
32
33 .. rubric:: Clone the Boost.Python project on gitorious
34
35 Using the same procedure as .above, clone the python project.  The
36 clone button is on `this page <http://gitorious.org/boost/python>`_.
37
38
39 .. rubric:: Clone your Boost clone the local
40    machine
41
42 .. I think this maybe should be the 2nd step.  That way, we're dealing
43 .. just with superproject clones and then we move on to the
44 .. subproject.
45
46 See :ref:`getting_started`, using the url of your clone on gitorious.
47 .. That sentence should be made clearer, but it may be best just to
48 .. repeat the instructions here so the poor reader doesn't have to
49 .. bounce around with hyperlinks.
50 The following steps will take place inside the local clone.
51
52 .. rubric:: Remove the old submodule
53
54 .. The following steps look **waaaay** too complicated.  We need to
55 .. find a way to make “point the python submodule at your clone” one
56 .. reasonably digestible step.
57
58 Remove these lines from :file:`.gitmodules`::
59
60   [submodule "src/python"]
61           path = src/python
62           url = git://gitorious.org/boost/python.git
63   
64 Add :file:`.gitmodules` to the pending commit::
65
66   git add .gitmodules
67
68 Remove these lines from :file:`.git/config`::
69
70   [submodule "src/python"]
71           url = git://gitorious.org/boost/python.git
72   
73 This is just for cleanliness, not part of the commit.
74
75 Remove the submodule from the cache::
76
77   % git rm --cached src/python 
78   rm 'src/python'
79
80 Git now shows that we're ready to delete it::
81
82   $ git status
83   # On branch 1.41.0
84   # Your branch is ahead of 'origin/1.41.0' by 1 commit.
85   #
86   # Changes to be committed:
87   #   (use "git reset HEAD <file>..." to unstage)
88   #
89   #       modified:   .gitmodules
90   #       deleted:    src/python
91   #
92   # Modified submodules:
93   #
94   # * src/python 028025b...0000000 (5):
95   #   < add some version numbers
96   #
97   # Untracked files:
98   #   (use "git add <file>..." to include in what will be committed)
99   #
100   #       src/python/
101   
102 Commit the change::
103
104   % git commit -m "changing python submodule..."
105   [1.41.0 489023d] changing python submodule...
106    1 files changed, 0 insertions(+), 1 deletions(-)
107    delete mode 160000 src/python
108   
109 Now you've removed the old submodule.
110
111 .. rubric:: add the new submodule
112
113 First remove the untracked directory corresponding to the submodule::
114
115   % rm -r src/python
116
117 Now add the new one::
118
119   % git submodule add git://gitorious.org/boost/straszheims-python.git src/python
120   Initialized empty Git repository in /home/troy/Projects/ryppl/tmp/boost2/src/python/.git/
121   remote: Counting objects: 1191, done.
122   remote: Compressing objects: 100% (768/768), done.
123   remote: Total 1191 (delta 468), reused 1117 (delta 396)
124   Receiving objects: 100% (1191/1191), 943.67 KiB | 590 KiB/s, done.
125   Resolving deltas: 100% (468/468), done.
126
127 .. note:: Notice I have used the ``git://`` url, not the ``git@`` url.
128           The ``git://`` url is readonly and is the only type of URL
129           that should be committed to the superproject.  The ``git@``
130           urls are readwrite and authenticated via SSH.  I will soon
131           use the latter to push commits from submodules, but I never
132           commit them to superprojects.
133
134 Now that the python repository now points to the right place::
135
136   $ grep url src/python/.git/config 
137           url = git://gitorious.org/boost/straszheims-python.git
138
139 Now git tells us that we've added the submodule, and shows the new
140 head commit::
141
142   % git status
143   # On branch 1.41.0
144   # Your branch is ahead of 'origin/1.41.0' by 2 commits.
145   #
146   # Changes to be committed:
147   #   (use "git reset HEAD <file>..." to unstage)
148   #
149   #       modified:   .gitmodules
150   #       new file:   src/python
151   #
152   # Modified submodules:
153   #
154   # * src/python 0000000...8d3d698 (21):
155   #   > that's basically it for overload resolution some upcoming numpy stuff mixed in :/
156   #
157   
158 And ``git diff --cached tells me``::
159
160   diff --git a/.gitmodules b/.gitmodules
161   index 30ccec5..64e4e98 100644
162   --- a/.gitmodules
163   +++ b/.gitmodules
164   @@ -10,3 +10,6 @@
165    [submodule "cmake"]
166           path = cmake
167           url = git://gitorious.org/ryppl/cmake.git
168   +[submodule "src/python"]
169   +       path = src/python
170   +       url = git://gitorious.org/boost/straszheims-python.git
171   diff --git a/src/python b/src/python
172   new file mode 160000
173   index 0000000..d6e0e56
174   --- /dev/null
175   +++ b/src/python
176   @@ -0,0 +1 @@
177   +Subproject commit d6e0e5699fcc241ff8470d5a35bbeb3946c1a0be
178   
179 Wherein you can see that the new submodule has been added to
180 :file:`.gitmodules` and the exact commit of the submodule is somehow
181 associated (``file mode 160000``) with the path :file:`src/python`.
182
183 Commit the change::
184
185   % git commit -m "add my python branch"
186   [1.41.0 64d5917] add my python branch
187    1 files changed, 1 insertions(+), 1 deletions(-)
188
189 Now you can push your changes to your ryppl branch.
190
191 Make and push modifications to your python project
192 """"""""""""""""""""""""""""""""""""""""""""""""""
193
194 Cd to project, modify a file, add to commit and commit::
195
196   $ cd src/python
197   $ echo "// modifications to python" >> include/boost/python.hpp 
198   $ git add include/boost/python.hpp
199   $ git commit -m "Dummy commit... demonstrating ryppl"
200
201 *Always* push your modifications to submodules before you commit the
202 modifications to the ryppl branch.  If you try to just push, git
203 complains::
204
205   $ git push
206   fatal: protocol error: expected sha/ref, got '
207   ----------------------------------------------
208   The git:// protocol is read-only.
209   
210   Please use the push url as listed on the repository page.
211   ----------------------------------------------'
212   
213 So add a remote that is writable.  I use the 'push' (``git@``) url and
214 name it *readwrite*::
215
216   $ git remote add readwrite git@gitorious.org:boost/straszheims-python.git
217
218 And push::
219
220   $ git push readwrite
221   Counting objects: 9, done.
222   Delta compression using up to 8 threads.
223   Compressing objects: 100% (4/4), done.
224   Writing objects: 100% (5/5), 453 bytes, done.
225   Total 5 (delta 2), reused 0 (delta 0)
226   => Syncing Gitorious... [OK]
227   To git@gitorious.org:boost/straszheims-python.git
228      8d3d698..d6e0e56  HEAD -> master
229
230 Now check your status up in the ryppl directory::
231
232   $ git status
233   # On branch 1.41.0
234   # Your branch is ahead of 'origin/1.41.0' by 3 commits.
235   #
236   # Changed but not updated:
237   #   (use "git add <file>..." to update what will be committed)
238   #   (use "git checkout -- <file>..." to discard changes in working directory)
239   #
240   #       modified:   src/python
241   #
242   
243 You can just commit this, but let's check some stuff first.  ``git submodule status`` shows ::
244
245   $ git submodule status
246    6dce83c277d48644fac187799876799eb66c97a2 cmake (heads/master)
247    0628a7a2d999bbbd62fd9877922c057f5f056114 src/accumulators (remotes/origin/1.41.0)
248    5cec8044c5408fadee71110194027b0e99b44721 src/algorithm (remotes/origin/1.41.0)
249    ...
250    49b781309f926ea9a2bed09091fe276f32f7a92a src/core (remotes/origin/1.41.0)
251   +8d3d698c598e1779f932e8a29e9131a23d55388e src/python  <-- plus
252   
253 The plus means that the head of the currently checked out submodule
254 doesn't match what is in the index, and ``submodule summary`` shows::
255
256     $ git submodule summary
257   * src/python 8d3d698...d6e0e56 (1):
258     > Dummy commit... demonstrating ryppl
259
260 specifically what the new commits are.  Now you'd commit and push the
261 modifications to the superproject::
262
263   $ git add src/python/
264   $ git commit -m "update python"
265   [1.41.0 709256c] update python
266    1 files changed, 1 insertions(+), 1 deletions(-)
267   % git push
268   Counting objects: 18, done.
269   Delta compression using up to 8 threads.
270   Compressing objects: 100% (15/15), done.
271   Writing objects: 100% (15/15), 1.19 KiB, done.
272   Total 15 (delta 11), reused 0 (delta 0)
273    
274 Now, you send email with your ryppl repository... when others check it
275 out and then ``submodule init`` and ``submodule update`` they get your
276 modifications to the python project.
277
278
279
280