docs/git.rst

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