MaintNotes

   1 Subject: A note from the maintainer
   2
   3 Welcome to git development community.
   4
   5 This message is written by the maintainer and talks about how Git
   6 project is managed, and how you can work with it.
   7
   8 * Mailing list and the community
   9
  10 The development is primarily done on the Git mailing list. Help
  11 requests, feature proposals, bug reports and patches should be sent to
  12 the list address <git@vger.kernel.org>.  You don't have to be
  13 subscribed to send messages.  The convention on the list is to keep
  14 everybody involved on Cc:, so it is unnecessary to say "Please Cc: me,
  15 I am not subscribed".
  16
  17 Before sending patches, please read Documentation/SubmittingPatches
  18 and Documentation/CodingGuidelines to familiarize yourself with the
  19 project convention.
  20
  21 If you sent a patch and you did not hear any response from anybody for
  22 several days, it could be that your patch was totally uninteresting,
  23 but it also is possible that it was simply lost in the noise.  Please
  24 do not hesitate to send a reminder message in such a case.  Messages
  25 getting lost in the noise is a sign that people involved don't have
  26 enough mental/time bandwidth to process them right at the moment, and
  27 it often helps to wait until the list traffic becomes calmer before
  28 sending such a reminder.
  29
  30 The list archive is available at a few public sites:
  31
  32         http://news.gmane.org/gmane.comp.version-control.git/
  33         http://marc.theaimsgroup.com/?l=git
  34         http://www.spinics.net/lists/git/
  35
  36 Some people seem to prefer to read it over NNTP:
  37
  38         nntp://news.gmane.org/gmane.comp.version-control.git
  39
  40 When you point at a message in a mailing list archive, using
  41 gmane is often the easiest to follow by readers, like this:
  42
  43         http://thread.gmane.org/gmane.comp.version-control.git/27/focus=217
  44
  45 as it also allows people who subscribe to the mailing list as gmane
  46 newsgroup to "jump to" the article.
  47
  48 Some members of the development community can sometimes also be found
  49 on the #git IRC channel on Freenode.  Its log is available at:
  50
  51         http://colabti.org/irclogger/irclogger_log/git
  52
  53 * Reporting bugs
  54
  55 When you think git does not behave as you expect, please do not stop
  56 your bug report with just "git does not work".  "I used git in this
  57 way, but it did not work" is not much better, neither is "I used git
  58 in this way, and X happend, which is broken".  It often is that git is
  59 correct to cause X happen in such a case, and it is your expectation
  60 that is broken. People would not know what other result Y you expected
  61 to see instead of X, if you left it unsaid.
  62
  63 Please remember to always state
  64
  65  - what you wanted to achieve;
  66
  67  - what you did (the version of git and the command sequence to reproduce
  68    the behavior);
  69
  70  - what you saw happen (X above);
  71
  72  - what you expected to see (Y above); and
  73
  74  - how the last two are different.
  75
  76 See http://www.chiark.greenend.org.uk/~sgtatham/bugs.html for further
  77 hints.
  78
  79 * Repositories, branches and documentation.
  80
  81 My public git.git repositories are at:
  82
  83         git://git.kernel.org/pub/scm/git/git.git/
  84         git://repo.or.cz/alt-git.git/
  85         https://github.com/git/git/
  86         https://code.google.com/p/git-core/
  87         git://git.sourceforge.jp/gitroot/git-core/git.git/
  88         git://git-core.git.sourceforge.net/gitroot/git-core/git-core/
  89
  90 A few gitweb interfaces are found at:
  91
  92         http://git.kernel.org/?p=git/git.git
  93         http://repo.or.cz/w/alt-git.git
  94
  95 Preformatted documentation from the tip of the "master" branch can be
  96 found in:
  97
  98         git://git.kernel.org/pub/scm/git/git-{htmldocs,manpages}.git/
  99         git://repo.or.cz/git-{htmldocs,manpages}.git/
 100         https://code.google.com/p/git-{htmldocs,manpages}.git/
 101         https://github.com/gitster/git-{htmldocs,manpages}.git/
 102
 103 There are four branches in git.git repository that track the source tree
 104 of git: "master", "maint", "next", and "pu".
 105
 106 The "master" branch is meant to contain what are very well tested and
 107 ready to be used in a production setting.  Every now and then, a "feature
 108 release" is cut from the tip of this branch and they typically are named
 109 with three dotted decimal digits.  The last such release was 1.7.8 done on
 110 Dec 2, 2011. You can expect that the tip of the "master" branch is always
 111 more stable than any of the released versions.
 112
 113 Whenever a feature release is made, "maint" branch is forked off from
 114 "master" at that point.  Obvious, safe and urgent fixes after a feature
 115 release are applied to this branch and maintenance releases are cut from
 116 it.  The maintenance releases are named with four dotted decimal, named
 117 after the feature release they are updates to; the last such release was
 118 1.7.7.4.  New features never go to this branch.  This branch is also
 119 merged into "master" to propagate the fixes forward.
 120
 121 A new development does not usually happen on "master". When you send a
 122 series of patches, after review on the mailing list, a separate topic
 123 branch is forked from the tip of "master" and your patches are queued
 124 there, and kept out of "master" while people test it out. The quality of
 125 topic branches are judged primarily by the mailing list discussions.
 126
 127 Topic branches that are in good shape are merged to the "next" branch. In
 128 general, the "next" branch always contains the tip of "master".  It might
 129 not be quite rock-solid, but is expected to work more or less without major
 130 breakage. The "next" branch is where new and exciting things take place. A
 131 topic that is in "next" is expected to be polished to perfection before it
 132 is merged to "master".
 133
 134 The "pu" (proposed updates) branch bundles all the remaining topic
 135 branches. The topics on the branch are not complete, well tested, nor well
 136 documented and need further work. When a topic that was in "pu" proves to
 137 be in testable shape, it is merged to "next".
 138
 139 You can run "git log --first-parent master..pu" to see what topics are
 140 currently in flight.  Sometimes, an idea that looked promising turns out
 141 to be not so good and the topic can be dropped from "pu" in such a case.
 142
 143 The two branches "master" and "maint" are never rewound, and "next"
 144 usually will not be either.  After a feature release is made from
 145 "master", however, "next" will be rebuilt from the tip of "master"
 146 using the topics that didn't make the cut in the feature release.
 147
 148 Note that being in "next" is not a guarantee to appear in the next
 149 release, nor even in any future release.  There were cases that topics
 150 needed reverting a few commits in them before graduating to "master",
 151 or a topic that already was in "next" was reverted from "next" because
 152 fatal flaws were found in it after it was merged.
 153
 154
 155 * Other people's trees, trusted lieutenants and credits.
 156
 157 Documentation/SubmittingPatches outlines to whom your proposed changes
 158 should be sent.  As described in contrib/README, I would delegate fixes
 159 and enhancements in contrib/ area to the primary contributors of them.
 160
 161 Although the following are included in git.git repository, they have their
 162 own authoritative repository and maintainers:
 163
 164  - git-gui/ comes from git-gui project, maintained by Pat Thoyts:
 165
 166         git://repo.or.cz/git-gui.git
 167
 168  - gitk-git/ comes from Paul Mackerras's gitk project:
 169
 170         git://git.kernel.org/pub/scm/gitk/gitk.git
 171
 172 I would like to thank everybody who helped to raise git into the current
 173 shape.  Especially I would like to thank the git list regulars whose help
 174 I have relied on and expect to continue relying on heavily:
 175
 176  - Linus Torvalds, Shawn Pearce, Johannes Schindelin, Nicolas Pitre,
 177    René Scharfe, Jeff King, Jonathan Nieder, Johan Herland, Johannes
 178    Sixt, Sverre Rabbelier, Michael J Gruber, Nguyễn Thái Ngọc Duy,
 179    Ævar Arnfjörð Bjarmason and Thomas Rast on general design and
 180    implementation issues and reviews on the mailing list.
 181
 182  - Shawn and Nicolas Pitre on pack issues.
 183
 184  - Martin Langhoff, Frank Lichtenheld and Ævar Arnfjörð Bjarmason on
 185    cvsserver and cvsimport.
 186
 187  - Paul Mackerras on gitk.
 188
 189  - Eric Wong, David D. Kilzer and Sam Vilain on git-svn.
 190
 191  - Simon Hausmann and Pete Wyckoff on git-p4.
 192
 193  - Jakub Narebski, John Hawley, Petr Baudis, Luben Tuikov, Giuseppe Bilotta on
 194    gitweb.
 195
 196  - J. Bruce Fields, Jonathan Nieder, Michael J Gruber and Thomas Rast on
 197    documentation (and countless others for proofreading and fixing).
 198
 199  - Alexandre Julliard on Emacs integration.
 200
 201  - David Aguilar and Charles Bailey for taking good care of git-mergetool
 202    (and Theodore Ts'o for creating it in the first place) and git-difftool.
 203
 204  - Johannes Schindelin, Johannes Sixt, Erik Faye-Lund, Pat Thoyts and others
 205    for their effort to move things forward on the Windows front.
 206
 207  - People on non-Linux platforms for keeping their eyes on portability;
 208    especially, Randal Schwartz, Theodore Ts'o, Jason Riedy, Thomas Glanzmann,
 209    Brandon Casey, Jeff King, Alex Riesen and countless others.