Commit | Line | Data |
---|---|---|
845c3ae2 WKG |
1 | ========================== |
2 | Git, Cloning and Patches | |
3 | ========================== | |
4 | ||
6729d65a WKG |
5 | .. contents:: Sections |
6 | :local: | |
7 | ||
8 | ||
909c639d WKG |
9 | GNU MediaGoblin uses git for all our version control and we have the |
10 | repositories hosted on `Gitorious <http://gitorious.org/>`_. We have | |
11 | two repositories: | |
845c3ae2 | 12 | |
909c639d WKG |
13 | * MediaGoblin software: http://gitorious.org/mediagoblin/mediagoblin |
14 | * MediaGoblin website: http://gitorious.org/mediagoblin/mediagoblin-website | |
15 | ||
16 | It's most likely you want to look at the software repository--not the | |
17 | website one. | |
18 | ||
19 | The rest of this chapter talks about using the software repository. | |
845c3ae2 WKG |
20 | |
21 | ||
22 | How to clone the project | |
23 | ======================== | |
24 | ||
25 | Do:: | |
26 | ||
27 | git clone git://gitorious.org/mediagoblin/mediagoblin.git | |
28 | ||
29 | ||
fb692417 WKG |
30 | How to contribute changes |
31 | ========================= | |
845c3ae2 | 32 | |
fb692417 WKG |
33 | Tie your changes to issues in the issue tracker |
34 | ----------------------------------------------- | |
909c639d | 35 | |
845c3ae2 | 36 | All patches should be tied to issues in the `issue tracker |
909c639d WKG |
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 | |
43 | doing. | |
44 | ||
fb692417 WKG |
45 | |
46 | Use bugfix branches to make changes | |
47 | ----------------------------------- | |
909c639d WKG |
48 | |
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. | |
52 | ||
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. | |
55 | ||
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 | |
60 | your changes. | |
61 | ||
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 | |
64 | another. | |
65 | ||
fb692417 WKG |
66 | |
67 | Properly document your changes | |
68 | ------------------------------ | |
909c639d WKG |
69 | |
70 | Include comments in the code. | |
71 | ||
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. | |
75 | ||
76 | Write comprehensive comments in the issue tracker about what you're | |
77 | doing and why. | |
78 | ||
79 | ||
fb692417 WKG |
80 | How to send us your changes |
81 | --------------------------- | |
909c639d | 82 | |
7577b7df | 83 | There are two ways to let us know how to get it: |
909c639d | 84 | |
f4391936 WKG |
85 | 1. *(preferred)* **push changes to publicly available git clone and |
86 | let us know where to find it** | |
909c639d | 87 | |
1e85d28e CAW |
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. | |
909c639d WKG |
91 | |
92 | 2. **attaching the patch files to the issue** | |
93 | ||
94 | Run:: | |
95 | ||
f4391936 | 96 | git format-patch --stdout <remote>/master > issue_<number>.patch |
909c639d | 97 | |
f4391936 WKG |
98 | ``format-patch`` creates a patch of all the commits that are in |
99 | your branch that aren't in ``<remote>/master``. The ``--stdout`` | |
100 | flag causes all this output to go to stdout where it's redirected | |
101 | to a file named ``issue_<number>.patch``. That file should be | |
102 | based on the issue you're working with. For example, | |
103 | ``issue_42.patch`` is a good filename and ``issue_42_rev2.patch`` | |
104 | is good if you did a revision of it. | |
105 | ||
106 | Having said all that, the filename isn't wildly important. | |
909c639d WKG |
107 | |
108 | ||
109 | Example workflow | |
110 | ================ | |
f4391936 | 111 | |
909c639d WKG |
112 | Here's an example workflow. |
113 | ||
114 | ||
115 | Contributing changes | |
116 | -------------------- | |
117 | ||
118 | Slartibartfast from the planet Magrathea far off in the universe has | |
fcdd1722 CAW |
119 | decided that he is bored with fjords and wants to fix issue 42 (the |
120 | meaning of life bug) and send us the changes. | |
909c639d WKG |
121 | |
122 | Slartibartfast has cloned the MediaGoblin repository and his clone | |
123 | lives on gitorious. | |
124 | ||
125 | Slartibartfast works locally. The remote named ``origin`` points to | |
126 | his clone on gitorious. The remote named ``gmg`` points to the | |
127 | MediaGoblin repository. | |
128 | ||
129 | Slartibartfast does the following: | |
130 | ||
131 | 1. Fetches the latest from the MediaGoblin repository:: | |
132 | ||
133 | git fetch --all -p | |
134 | ||
f4391936 WKG |
135 | This tells ``git fetch`` to fetch all the recent data from all of |
136 | the remotes (``--all``) and prune any branches that have been | |
137 | deleted in the remotes (``-p``). | |
138 | ||
909c639d | 139 | 2. Creates a branch from the tip of the MediaGoblin repository (the |
fcdd1722 | 140 | remote is named ``gmg``) master branch called ``bug42_meaning_of_life``:: |
909c639d | 141 | |
fcdd1722 | 142 | git checkout -b bug42_meaning_of_life gmg/master |
909c639d | 143 | |
f4391936 WKG |
144 | This creates a new branch (``-b``) named ``bug42_meaning_of_life`` based |
145 | on the tip of the ``master`` branch of the remote named ``gmg`` and checks | |
146 | it out. | |
147 | ||
fcdd1722 | 148 | 3. Slartibartfast works hard on his changes in the ``bug42_meaning_of_life`` |
909c639d WKG |
149 | branch. When done, he wants to notify us that he has made changes |
150 | he wants us to see. | |
151 | ||
f4391936 | 152 | 4. Slartibartfast pushes his changes to his clone:: |
909c639d | 153 | |
fcdd1722 | 154 | git push origin bug42_meaning_of_life --set-upstream |
909c639d | 155 | |
f4391936 WKG |
156 | This pushes the changes in the ``bug42_meaning_of_life`` branch to the |
157 | remote named ``origin``. | |
158 | ||
909c639d WKG |
159 | 5. Slartibartfast adds a comment to issue 42 with the url for his |
160 | repository and the name of the branch he put the code in. He also | |
161 | explains what he did and why it addresses the issue. | |
162 | ||
163 | ||
164 | Updating a contribution | |
165 | ----------------------- | |
166 | ||
167 | Slartibartfast brushes his hands off with the sense of accomplishment | |
168 | that comes with the knowledge of a job well done. He stands, wanders | |
169 | over to get a cup of water, then realizes that he forgot to run the | |
170 | unit tests! | |
171 | ||
172 | He runs the unit tests and discovers there's a bug in the code! | |
173 | ||
174 | Then he does this: | |
175 | ||
fcdd1722 | 176 | 1. He checks out the ``bug42_meaning_of_life`` branch:: |
845c3ae2 | 177 | |
fcdd1722 | 178 | git checkout bug42_meaning_of_life |
845c3ae2 | 179 | |
fcdd1722 | 180 | 2. He fixes the bug and checks it into the ``bug42_meaning_of_life`` branch. |
845c3ae2 | 181 | |
909c639d | 182 | 3. He pushes his changes to his clone (the remote is named ``origin``):: |
845c3ae2 | 183 | |
fcdd1722 | 184 | git push origin bug42_meaning_of_life |
845c3ae2 | 185 | |
909c639d WKG |
186 | 4. He adds another comment to issue 42 explaining about the mistake |
187 | and how he fixed it and that he's pushed the new change to the | |
fcdd1722 | 188 | ``bug42_meaning_of_life`` branch of his publicly available clone. |
845c3ae2 | 189 | |
845c3ae2 | 190 | |
909c639d WKG |
191 | What happens next |
192 | ----------------- | |
845c3ae2 | 193 | |
909c639d WKG |
194 | Slartibartfast is once again happy with his work. He finds issue 42 |
195 | in the issue tracker and adds a comment saying he submitted a merge | |
196 | request with his changes and explains what they are. | |
845c3ae2 | 197 | |
909c639d WKG |
198 | Later, someone checks out his code and finds a problem with it. He |
199 | adds a comment to the issue tracker specifying the problem and asks | |
200 | Slartibartfast to fix it. Slartibartfst goes through the above steps | |
fcdd1722 | 201 | again, fixes the issue, pushes it to his ``bug42_meaning_of_life`` branch and adds |
909c639d | 202 | another comment to the issue tracker about how he fixed it. |
845c3ae2 | 203 | |
909c639d WKG |
204 | Later, someone checks out his code and is happy with it. Someone |
205 | pulls it into the master branch of the MediaGoblin repository and adds | |
206 | another comment to the issue and probably closes the issue out. | |
845c3ae2 | 207 | |
909c639d | 208 | Slartibartfast is notified of this. Slartibartfast does a:: |
845c3ae2 | 209 | |
909c639d | 210 | git fetch --all |
845c3ae2 | 211 | |
909c639d | 212 | The changes show up in the ``master`` branch of the ``gmg`` remote. |
fcdd1722 CAW |
213 | Slartibartfast now deletes his ``bug42_meaning_of_life`` branch |
214 | because he doesn't need it anymore. | |
845c3ae2 WKG |
215 | |
216 | ||
217 | How to learn git | |
218 | ================ | |
219 | ||
220 | Check out :ref:`hacking-howto-git`! |