MaintNotes

   1 Subject: A note from the maintainer
   2
   3 Welcome to the 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 may be a sign that those who can evaluate
  26 your patch don't have enough mental/time bandwidth to process them
  27 right at the moment, and it often helps to wait until the list traffic
  28 becomes calmer before 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 For those who 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 be found on
  49 the #git and #git-devel IRC channels on Freenode.  Their logs are
  50 available at:
  51
  52         http://colabti.org/irclogger/irclogger_log/git
  53         http://colabti.org/irclogger/irclogger_log/git-devel
  54
  55 * Reporting bugs
  56
  57 When you think git does not behave as you expect, please do not stop
  58 your bug report with just "git does not work".  "I used git in this
  59 way, but it did not work" is not much better, neither is "I used git
  60 in this way, and X happend, which is broken".  It often is that git is
  61 correct to cause X happen in such a case, and it is your expectation
  62 that is broken. People would not know what other result Y you expected
  63 to see instead of X, if you left it unsaid.
  64
  65 Please remember to always state
  66
  67  - what you wanted to achieve;
  68
  69  - what you did (the version of git and the command sequence to reproduce
  70    the behavior);
  71
  72  - what you saw happen (X above);
  73
  74  - what you expected to see (Y above); and
  75
  76  - how the last two are different.
  77
  78 See http://www.chiark.greenend.org.uk/~sgtatham/bugs.html for further
  79 hints.
  80
  81 * Repositories, branches and documentation.
  82
  83 My public git.git repositories are at:
  84
  85         git://git.kernel.org/pub/scm/git/git.git/
  86         https://kernel.googlesource.com/pub/scm/git/git
  87         git://repo.or.cz/alt-git.git/
  88         https://github.com/git/git/
  89         https://code.google.com/p/git-core/
  90         git://git.sourceforge.jp/gitroot/git-core/git.git/
  91         git://git-core.git.sourceforge.net/gitroot/git-core/git-core/
  92
  93 A few web interfaces are found at:
  94
  95         http://git.kernel.org/?p=git/git.git
  96         https://kernel.googlesource.com/pub/scm/git/git
  97         http://repo.or.cz/w/alt-git.git
  98
  99 Preformatted documentation from the tip of the "master" branch can be
 100 found in:
 101
 102         git://git.kernel.org/pub/scm/git/git-{htmldocs,manpages}.git/
 103         git://repo.or.cz/git-{htmldocs,manpages}.git/
 104         https://code.google.com/p/git-{htmldocs,manpages}.git/
 105         https://github.com/gitster/git-{htmldocs,manpages}.git/
 106
 107 You can browse the HTML manual pages at:
 108
 109         http://git-htmldocs.googlecode.com/git/git.html
 110
 111 There are four branches in git.git repository that track the source tree
 112 of git: "master", "maint", "next", and "pu".
 113
 114 The "master" branch is meant to contain what are very well tested and
 115 ready to be used in a production setting.  Every now and then, a
 116 "feature release" is cut from the tip of this branch.  They used to be
 117 named with three dotted decimal digits (e.g. "1.8.5"), but recently we
 118 switched the versioning scheme and "feature releases" are named with
 119 three-dotted decimal digits that ends with ".0" (e.g. "1.9.0").
 120
 121 The last such release was 1.9.0 done on Feb 14, 2014. You can expect
 122 that the tip of the "master" branch is always more stable than any of
 123 the released versions.
 124
 125 Whenever a feature release is made, "maint" branch is forked off from
 126 "master" at that point.  Obvious, safe and urgent fixes after a
 127 feature release are applied to this branch and maintenance releases
 128 are cut from it.  The maintenance releases used to be named with four
 129 dotted decimal, named after the feature release they are updates to
 130 (e.g. "1.8.5.1" was the first maintenance release for "1.8.5" feature
 131 release).  These days, maintenance releases are named by incrementing
 132 the last digit of three-dotted decimal name (e.g. "1.9.1" is the first
 133 maintenance relaese for "1.9.0" series).
 134
 135 New features never go to the 'maint' branch.  This branch is also
 136 merged into "master" to propagate the fixes forward as needed.
 137
 138 A new development does not usually happen on "master". When you send a
 139 series of patches, after review on the mailing list, a separate topic
 140 branch is forked from the tip of "master" and your patches are queued
 141 there, and kept out of "master" while people test it out. The quality of
 142 topic branches are judged primarily by the mailing list discussions.
 143
 144 Topic branches that are in good shape are merged to the "next" branch. In
 145 general, the "next" branch always contains the tip of "master".  It might
 146 not be quite rock-solid, but is expected to work more or less without major
 147 breakage. The "next" branch is where new and exciting things take place. A
 148 topic that is in "next" is expected to be polished to perfection before it
 149 is merged to "master".
 150
 151 The "pu" (proposed updates) branch bundles all the remaining topic
 152 branches the maintainer happens to have.  There is no guarantee that
 153 the maintainer has enough bandwidth to pick up any and all topics that
 154 are remotely promising from the list traffic, so please do not read
 155 too much into a topic being on (or not on) the "pu" branch.  This
 156 branch is mainly to remind the maintainer that the topics in them may
 157 turn out to be interesting when they are polished, nothing more.  The
 158 topics on this branch aren't usually complete, well tested, or well
 159 documented and they need further work.  When a topic that was in "pu"
 160 proves to be in a testable shape, it is merged to "next".
 161
 162 You can run "git log --first-parent master..pu" to see what topics are
 163 currently in flight.  Sometimes, an idea that looked promising turns out
 164 to be not so good and the topic can be dropped from "pu" in such a case.
 165
 166 The two branches "master" and "maint" are never rewound, and "next"
 167 usually will not be either.  After a feature release is made from
 168 "master", however, "next" will be rebuilt from the tip of "master"
 169 using the topics that didn't make the cut in the feature release.
 170
 171 Note that being in "next" is not a guarantee to appear in the next
 172 release, nor even in any future release.  There were cases that topics
 173 needed reverting a few commits in them before graduating to "master",
 174 or a topic that already was in "next" was reverted from "next" because
 175 fatal flaws were found in it after it was merged to "next".
 176
 177
 178 * Other people's trees, trusted lieutenants and credits.
 179
 180 Documentation/SubmittingPatches outlines to whom your proposed changes
 181 should be sent.  As described in contrib/README, I would delegate fixes
 182 and enhancements in contrib/ area to the primary contributors of them.
 183
 184 Although the following are included in git.git repository, they have their
 185 own authoritative repository and maintainers:
 186
 187  - git-gui/ comes from git-gui project, maintained by Pat Thoyts:
 188
 189         git://repo.or.cz/git-gui.git
 190
 191  - gitk-git/ comes from Paul Mackerras's gitk project:
 192
 193         git://ozlabs.org/~paulus/gitk
 194
 195  - po/ comes from the localization coordinator, Jiang Xin:
 196
 197         https://github.com/git-l10n/git-po/
 198