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 WKG |
82 | |
83 | There are three ways to let us know how to get it: | |
84 | ||
85 | 1. (preferred) **push changes to publicly available git clone and let | |
86 | us know where to find it** | |
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 | ||
96 | git format-patch -o patches <remote>/master | |
97 | ||
98 | Then tar up the newly created ``patches`` directory and attach the | |
99 | directory to the issue. | |
100 | ||
101 | ||
102 | Example workflow | |
103 | ================ | |
104 | Here's an example workflow. | |
105 | ||
106 | ||
107 | Contributing changes | |
108 | -------------------- | |
109 | ||
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 | |
112 | send us the changes. | |
113 | ||
114 | Slartibartfast has cloned the MediaGoblin repository and his clone | |
115 | lives on gitorious. | |
116 | ||
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. | |
120 | ||
121 | Slartibartfast does the following: | |
122 | ||
123 | 1. Fetches the latest from the MediaGoblin repository:: | |
124 | ||
125 | git fetch --all -p | |
126 | ||
127 | 2. Creates a branch from the tip of the MediaGoblin repository (the | |
128 | remote is named ``gmg``) master branch called ``issue_42``:: | |
129 | ||
130 | git checkout -b issue_42 gmg/master | |
131 | ||
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 | |
134 | he wants us to see. | |
135 | ||
136 | 4. Slartibartfast pushes his changes to his clone (the remote is named | |
137 | ``origin``):: | |
138 | ||
595944d4 | 139 | git push origin issue_42 --set-upstream |
909c639d WKG |
140 | |
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. | |
144 | ||
145 | ||
146 | Updating a contribution | |
147 | ----------------------- | |
148 | ||
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 | |
152 | unit tests! | |
153 | ||
154 | He runs the unit tests and discovers there's a bug in the code! | |
155 | ||
156 | Then he does this: | |
157 | ||
158 | 1. He checks out the ``issue_42`` branch:: | |
845c3ae2 | 159 | |
909c639d | 160 | git checkout issue_42 |
845c3ae2 | 161 | |
909c639d | 162 | 2. He fixes the bug and checks it into the ``issue_42`` branch. |
845c3ae2 | 163 | |
909c639d | 164 | 3. He pushes his changes to his clone (the remote is named ``origin``):: |
845c3ae2 | 165 | |
909c639d | 166 | git push origin issue_42 |
845c3ae2 | 167 | |
909c639d WKG |
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. | |
845c3ae2 | 171 | |
845c3ae2 | 172 | |
909c639d WKG |
173 | What happens next |
174 | ----------------- | |
845c3ae2 | 175 | |
909c639d WKG |
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. | |
845c3ae2 | 179 | |
909c639d WKG |
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. | |
845c3ae2 | 185 | |
909c639d WKG |
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. | |
845c3ae2 | 189 | |
909c639d | 190 | Slartibartfast is notified of this. Slartibartfast does a:: |
845c3ae2 | 191 | |
909c639d | 192 | git fetch --all |
845c3ae2 | 193 | |
909c639d WKG |
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 | |
196 | need it anymore. | |
845c3ae2 WKG |
197 | |
198 | ||
199 | How to learn git | |
200 | ================ | |
201 | ||
202 | Check out :ref:`hacking-howto-git`! |