docs/git.rst

   1 ==========================
   2  Git, Cloning and Patches
   3 ==========================
   4
   5 GNU MediaGoblin uses git for all our version control and we have the
   6 repositories hosted on `Gitorious <http://gitorious.org/>`_.  We have
   7 two repositories:
   8
   9 * MediaGoblin software: http://gitorious.org/mediagoblin/mediagoblin
  10 * MediaGoblin website: http://gitorious.org/mediagoblin/mediagoblin-website
  11
  12 It's most likely you want to look at the software repository--not the
  13 website one.
  14
  15 The rest of this chapter talks about using the software repository.
  16
  17
  18 How to clone the project
  19 ========================
  20
  21 Do::
  22
  23     git clone git://gitorious.org/mediagoblin/mediagoblin.git
  24
  25
  26 How to send in patches
  27 ======================
  28
  29 **Tie your changes to issues in the issue tracker**
  30
  31 All patches should be tied to issues in the `issue tracker
  32 <http://bugs.foocorp.net/projects/mediagoblin/issues>`_.  That makes
  33 it a lot easier for everyone to track proposed changes and make sure
  34 your hard work doesn't get dropped on the floor!  If there isn't an
  35 issue for what you're working on, please create one.  The better the
  36 description of what it is you're trying to fix/implement, the better
  37 everyone else is able to understand why you're doing what you're
  38 doing.
  39
  40 **Use bugfix branches**
  41
  42 The best way to isolate your changes is to create a branch based off
  43 of the MediaGoblin repository master branch, do the changes related to
  44 that one issue there, and then let us know how to get it.
  45
  46 It's much easier on us if you isolate your changes to a branch focused
  47 on the issue.  Then we don't have to sift through things.
  48
  49 It's much easier on you if you isolate your changes to a branch
  50 focused on the issue.  Then when we merge your changes in, you just
  51 have to do a ``git fetch`` and that's it.  This is especially true if
  52 we reject some of your changes, but accept others or otherwise tweak
  53 your changes.
  54
  55 Further, if you isolate your changes to a branch, then you can work on
  56 multiple issues at the same time and they don't conflict with one
  57 another.
  58
  59 **Properly document your changes**
  60
  61 Include comments in the code.
  62
  63 Write comprehensive commit messages.  The better your commit message
  64 is at describing what you did and why, the easier it is for us to
  65 quickly accept your patch.
  66
  67 Write comprehensive comments in the issue tracker about what you're
  68 doing and why.
  69
  70
  71 **How to send us your changes**
  72
  73 There are three ways to let us know how to get it:
  74
  75 1. (preferred) **push changes to publicly available git clone and let
  76    us know where to find it**
  77
  78    Push your branch to your publicly available git clone and add a
  79    comment to the issue with the url for your clone and the branch to
  80    look at.
  81
  82 2. **attaching the patch files to the issue**
  83
  84    Run::
  85
  86        git format-patch -o patches <remote>/master
  87
  88    Then tar up the newly created ``patches`` directory and attach the
  89    directory to the issue.
  90
  91
  92 Example workflow
  93 ================
  94 Here's an example workflow.
  95
  96
  97 Contributing changes
  98 --------------------
  99
 100 Slartibartfast from the planet Magrathea far off in the universe has
 101 decided that he is bored with fjords and wants to fix issue 42 and
 102 send us the changes.
 103
 104 Slartibartfast has cloned the MediaGoblin repository and his clone
 105 lives on gitorious.
 106
 107 Slartibartfast works locally.  The remote named ``origin`` points to
 108 his clone on gitorious.  The remote named ``gmg`` points to the
 109 MediaGoblin repository.
 110
 111 Slartibartfast does the following:
 112
 113 1. Fetches the latest from the MediaGoblin repository::
 114
 115        git fetch --all -p
 116
 117 2. Creates a branch from the tip of the MediaGoblin repository (the
 118    remote is named ``gmg``) master branch called ``issue_42``::
 119
 120        git checkout -b issue_42 gmg/master
 121
 122 3. Slartibartfast works hard on his changes in the ``issue_42``
 123    branch.  When done, he wants to notify us that he has made changes
 124    he wants us to see.
 125
 126 4. Slartibartfast pushes his changes to his clone (the remote is named
 127    ``origin``)::
 128
 129        git push origin issue_42
 130
 131 5. Slartibartfast adds a comment to issue 42 with the url for his
 132    repository and the name of the branch he put the code in.  He also
 133    explains what he did and why it addresses the issue.
 134
 135
 136 Updating a contribution
 137 -----------------------
 138
 139 Slartibartfast brushes his hands off with the sense of accomplishment
 140 that comes with the knowledge of a job well done.  He stands, wanders
 141 over to get a cup of water, then realizes that he forgot to run the
 142 unit tests!
 143
 144 He runs the unit tests and discovers there's a bug in the code!
 145
 146 Then he does this:
 147
 148 1. He checks out the ``issue_42`` branch::
 149
 150        git checkout issue_42
 151
 152 2. He fixes the bug and checks it into the ``issue_42`` branch.
 153
 154 3. He pushes his changes to his clone (the remote is named ``origin``)::
 155
 156        git push origin issue_42
 157
 158 4. He adds another comment to issue 42 explaining about the mistake
 159    and how he fixed it and that he's pushed the new change to the
 160    ``issue_42`` branch of his publicly available clone.
 161
 162
 163 What happens next
 164 -----------------
 165
 166 Slartibartfast is once again happy with his work.  He finds issue 42
 167 in the issue tracker and adds a comment saying he submitted a merge
 168 request with his changes and explains what they are.
 169
 170 Later, someone checks out his code and finds a problem with it.  He
 171 adds a comment to the issue tracker specifying the problem and asks
 172 Slartibartfast to fix it.  Slartibartfst goes through the above steps
 173 again, fixes the issue, pushes it to his ``issue_42`` branch and adds
 174 another comment to the issue tracker about how he fixed it.
 175
 176 Later, someone checks out his code and is happy with it.  Someone
 177 pulls it into the master branch of the MediaGoblin repository and adds
 178 another comment to the issue and probably closes the issue out.
 179
 180 Slartibartfast is notified of this.  Slartibartfast does a::
 181
 182    git fetch --all
 183
 184 The changes show up in the ``master`` branch of the ``gmg`` remote.
 185 Slartibartfast now deletes his ``issue_42`` branch because he doesn't
 186 need it anymore.
 187
 188
 189 How to learn git
 190 ================
 191
 192 Check out :ref:`hacking-howto-git`!