1 ==========================
2 Git, Cloning and Patches
3 ==========================
9 GNU MediaGoblin uses git for all our version control and we have the
10 repositories hosted on `Gitorious <http://gitorious.org/>`_. We have
13 * MediaGoblin software: http://gitorious.org/mediagoblin/mediagoblin
14 * MediaGoblin website: http://gitorious.org/mediagoblin/mediagoblin-website
16 It's most likely you want to look at the software repository--not the
19 The rest of this chapter talks about using the software repository.
22 How to clone the project
23 ========================
27 git clone git://gitorious.org/mediagoblin/mediagoblin.git
30 How to contribute changes
31 =========================
33 Tie your changes to issues in the issue tracker
34 -----------------------------------------------
36 All patches should be tied to issues in the `issue tracker
37 <http://bugs.foocorp.net/projects/mediagoblin/issues>`_. That makes
38 it a lot easier for everyone to track proposed changes and make sure
39 your hard work doesn't get dropped on the floor! If there isn't an
40 issue for what you're working on, please create one. The better the
41 description of what it is you're trying to fix/implement, the better
42 everyone else is able to understand why you're doing what you're
46 Use bugfix branches to make changes
47 -----------------------------------
49 The best way to isolate your changes is to create a branch based off
50 of the MediaGoblin repository master branch, do the changes related to
51 that one issue there, and then let us know how to get it.
53 It's much easier on us if you isolate your changes to a branch focused
54 on the issue. Then we don't have to sift through things.
56 It's much easier on you if you isolate your changes to a branch
57 focused on the issue. Then when we merge your changes in, you just
58 have to do a ``git fetch`` and that's it. This is especially true if
59 we reject some of your changes, but accept others or otherwise tweak
62 Further, if you isolate your changes to a branch, then you can work on
63 multiple issues at the same time and they don't conflict with one
67 Properly document your changes
68 ------------------------------
70 Include comments in the code.
72 Write comprehensive commit messages. The better your commit message
73 is at describing what you did and why, the easier it is for us to
74 quickly accept your patch.
76 Write comprehensive comments in the issue tracker about what you're
80 How to send us your changes
81 ---------------------------
83 There are three ways to let us know how to get it:
85 1. (preferred) **push changes to publicly available git clone and let
86 us know where to find it**
88 Push your feature/bugfix/issue branch to your publicly available
89 git clone and add a comment to the issue with the url for your
90 clone and the branch to look at.
92 2. **attaching the patch files to the issue**
96 git format-patch -o patches <remote>/master
98 Then tar up the newly created ``patches`` directory and attach the
99 directory to the issue.
104 Here's an example workflow.
110 Slartibartfast from the planet Magrathea far off in the universe has
111 decided that he is bored with fjords and wants to fix issue 42 and
114 Slartibartfast has cloned the MediaGoblin repository and his clone
117 Slartibartfast works locally. The remote named ``origin`` points to
118 his clone on gitorious. The remote named ``gmg`` points to the
119 MediaGoblin repository.
121 Slartibartfast does the following:
123 1. Fetches the latest from the MediaGoblin repository::
127 2. Creates a branch from the tip of the MediaGoblin repository (the
128 remote is named ``gmg``) master branch called ``issue_42``::
130 git checkout -b issue_42 gmg/master
132 3. Slartibartfast works hard on his changes in the ``issue_42``
133 branch. When done, he wants to notify us that he has made changes
136 4. Slartibartfast pushes his changes to his clone (the remote is named
139 git push origin issue_42 --set-upstream
141 5. Slartibartfast adds a comment to issue 42 with the url for his
142 repository and the name of the branch he put the code in. He also
143 explains what he did and why it addresses the issue.
146 Updating a contribution
147 -----------------------
149 Slartibartfast brushes his hands off with the sense of accomplishment
150 that comes with the knowledge of a job well done. He stands, wanders
151 over to get a cup of water, then realizes that he forgot to run the
154 He runs the unit tests and discovers there's a bug in the code!
158 1. He checks out the ``issue_42`` branch::
160 git checkout issue_42
162 2. He fixes the bug and checks it into the ``issue_42`` branch.
164 3. He pushes his changes to his clone (the remote is named ``origin``)::
166 git push origin issue_42
168 4. He adds another comment to issue 42 explaining about the mistake
169 and how he fixed it and that he's pushed the new change to the
170 ``issue_42`` branch of his publicly available clone.
176 Slartibartfast is once again happy with his work. He finds issue 42
177 in the issue tracker and adds a comment saying he submitted a merge
178 request with his changes and explains what they are.
180 Later, someone checks out his code and finds a problem with it. He
181 adds a comment to the issue tracker specifying the problem and asks
182 Slartibartfast to fix it. Slartibartfst goes through the above steps
183 again, fixes the issue, pushes it to his ``issue_42`` branch and adds
184 another comment to the issue tracker about how he fixed it.
186 Later, someone checks out his code and is happy with it. Someone
187 pulls it into the master branch of the MediaGoblin repository and adds
188 another comment to the issue and probably closes the issue out.
190 Slartibartfast is notified of this. Slartibartfast does a::
194 The changes show up in the ``master`` branch of the ``gmg`` remote.
195 Slartibartfast now deletes his ``issue_42`` branch because he doesn't
202 Check out :ref:`hacking-howto-git`!