This message is written by the maintainer and talks about how Git
project is managed, and how you can work with it.
-* IRC and Mailing list
+* Mailing list and the community
-Members of the development community can sometimes be found on #git
-IRC channel on Freenode. Its log is available at:
+The development is primarily done on the Git mailing list. Help
+requests, feature proposals, bug reports and patches should be sent to
+the list address <git@vger.kernel.org>. You don't have to be
+subscribed to send messages. The convention on the list is to keep
+everybody involved on Cc:, so it is unnecessary to ask "Please Cc: me,
+I am not subscribed".
- http://colabti.org/irclogger/irclogger_log/git
-
-The development is primarily done on the Git mailing list. If you have
-patches, please send them to the list address (git@vger.kernel.org).
-following Documentation/SubmittingPatches. You don't have to be
-subscribed to send messages there, and the convention is to Cc:
-everybody involved, so you don't even have to say "Please Cc: me, I am
-not subscribed".
+Before sending patches, please read Documentation/SubmittingPatches
+and Documentation/CodingGuidelines to familiarize yourself with the
+project convention.
If you sent a patch and you did not hear any response from anybody for
-several days, it could be that your patch was totally uninteresting, but
-it also is possible that it was simply lost in the noise. Please do not
-hesitate to send a reminder message politely in such a case. Messages
-getting lost in the noise is a sign that people involved don't have enough
-mental/time bandwidth to process them right at the moment, and it often
-helps to wait until the list traffic becomes calmer before sending such a
-reminder.
+several days, it could be that your patch was totally uninteresting,
+but it also is possible that it was simply lost in the noise. Please
+do not hesitate to send a reminder message in such a case. Messages
+getting lost in the noise is a sign that people involved don't have
+enough mental/time bandwidth to process them right at the moment, and
+it often helps to wait until the list traffic becomes calmer before
+sending such a reminder.
The list archive is available at a few public sites as well:
http://thread.gmane.org/gmane.comp.version-control.git/27/focus=217
-as it also allows people who subscribe to the mailing list as
-gmane newsgroup to "jump to" the article.
+as it also allows people who subscribe to the mailing list as gmane
+newsgroup to "jump to" the article.
+
+Some members of the development community can sometimes also be found
+on the #git IRC channel on Freenode. Its log is available at:
+
+ http://colabti.org/irclogger/irclogger_log/git
+
+* Reporting bugs
+
+When you think git does not behave as you expect, please do not stop your
+bug report with just "git does not work". "I tried to do X but it did not
+work" is not much better, neither is "I tried to do X and git did Y, which
+is broken". It often is that what you expect is _not_ what other people
+expect, and chances are that what you expect is very different from what
+people who have worked on git have expected (otherwise, the behavior
+would have been changed to match that expectation long time ago).
+
+Please remember to always state
+
+ - what you wanted to do;
+
+ - what you did (the version of git and the command sequence to reproduce
+ the behavior);
+
+ - what you saw happen;
+
+ - what you expected to see; and
+
+ - how the last two are different.
+
+See http://www.chiark.greenend.org.uk/~sgtatham/bugs.html for further
+hints.
* Repositories, branches and documentation.
http://repo.or.cz/w/alt-git.git
There are three branches in git.git repository that are not about the
-source tree of git: "todo", "html" and "man". The first one was meant to
-contain TODO list for me, but I am not good at maintaining such a list and
-it is in an abandoned state. The branch mostly is used to keep some
-helper scripts I use to maintain git and the regular "What's cooking"
-messages these days.
-
-The "html" and "man" are autogenerated documentation from the tip of the
-"master" branch; the tip of "html" is extracted to be visible at
+source tree of git: "html", "man", and "todo".
+
+The "html" and "man" are auto-generated documentation from the tip of
+the "master" branch; the tip of "html" is extracted to be visible at
kernel.org at:
http://www.kernel.org/pub/software/scm/git/docs/
-The above URL is the top-level documentation page, and it has
-links to documentation of older releases.
+The above URL is the top-level documentation page, and it has links to
+documentation of older releases.
-The script to maintain these two documentation branches are found in the
-"todo" branch as dodoc.sh, if you are interested. It is a demonstration
-of how to use a post-update hook to automate a task after pushing into a
+The "todo" branch was originally meant to contain a TODO list for me,
+but is mostly used to keep some helper scripts I use to maintain git.
+For example, the script to maintain the two documentation branches are
+found there as dodoc.sh, which may be a good demonstration of how to
+use a post-update hook to automate a task after pushing into a
repository.
There are four branches in git.git repository that track the source tree
-of git: "master", "maint", "next", and "pu". I may add more maintenance
-branches (e.g. "maint-1.6.3") if we have hugely backward incompatible
-feature updates in the future to keep an older release alive; I may not,
-but the distributed nature of git means any volunteer can run a
-stable-tree like that herself.
+of git: "master", "maint", "next", and "pu".
The "master" branch is meant to contain what are very well tested and
-ready to be used in a production setting. There could occasionally be
-minor breakages or brown paper bag bugs but they are not expected to be
-anything major, and more importantly quickly and trivially fixable. Every
-now and then, a "feature release" is cut from the tip of this branch and
-they typically are named with three dotted decimal digits. The last such
-release was 1.7.4 done on Jan 30, 2011. You can expect that the tip of
-the "master" branch is always more stable than any of the released
-versions.
+ready to be used in a production setting. Every now and then, a "feature
+release" is cut from the tip of this branch and they typically are named
+with three dotted decimal digits. The last such release was 1.7.5 done on
+Apr 24, 2011. You can expect that the tip of the "master" branch is
+always more stable than any of the released versions.
Whenever a feature release is made, "maint" branch is forked off from
"master" at that point. Obvious, safe and urgent fixes after a feature
release are applied to this branch and maintenance releases are cut from
it. The maintenance releases are named with four dotted decimal, named
after the feature release they are updates to; the last such release was
-1.7.3.5. New features never go to this branch. This branch is also
+1.7.4.5. New features never go to this branch. This branch is also
merged into "master" to propagate the fixes forward.
-A trivial and safe enhancement goes directly on top of "master". A new
-development, either initiated by myself or more often by somebody who
-found his or her own itch to scratch, does not usually happen on "master",
-however. Instead, a separate topic branch is forked from the tip of
-"master", and it first is tested in isolation; I may make minimum fixups
-at this point. Usually there are a handful such topic branches that are
-running ahead of "master" in git.git repository. I do not publish the tip
-of these branches in my public repository, however, partly to keep the
-number of branches that downstream developers need to worry about low, and
-primarily because I am lazy.
-
-The quality of topic branches are judged primarily by the mailing list
-discussions. Some of them start out as "good idea but obviously is broken
-in some areas (e.g. breaks the existing testsuite)" and then with some
-more work (either by the original contributor's effort or help from other
-people on the list) becomes "more or less done and can now be tested by
-wider audience". Luckily, most of them start out in the latter, better
-shape.
-
-The "next" branch is to merge and test topic branches in the latter
-category. In general, the branch always contains the tip of "master". It
-might not be quite rock-solid production ready, but is expected to work
-more or less without major breakage. I usually use "next" version of git
-for my own work, so it cannot be _that_ broken to prevent me from
-integrating and pushing the changes out. The "next" branch is where new
-and exciting things take place.
+A new development does not usually happen on "master". When you send a
+series of patches, after review on the mailing list, a separate topic
+branch is forked from the tip of "master" and your patches are queued
+there, and kept out of "master" while people test it out. The quality of
+topic branches are judged primarily by the mailing list discussions.
+
+Topic branches that are in good shape are merged to the "next" branch. In
+general, the "next" branch always contains the tip of "master". It might
+not be quite rock-solid production ready, but is expected to work more or
+less without major breakage. The "next" branch is where new and exciting
+things take place. A topic that is in "next" is expected to be polished to
+perfection before it is merged to "master" (that's why "master" can be
+expected to stay more stable than any released version).
+
+The "pu" (proposed updates) branch bundles all the remaining topic
+branches. The topics on the branch are not complete, well tested, nor well
+documented and need further work. When a topic that was in "pu" proves to
+be in testable shape, it is merged to "next".
+
+You can run "git log --first-parent master..pu" to see what topics are
+currently in flight. Sometimes, an idea that looked promising turns out
+to be not so good and the topic can be dropped from "pu" in such a case.
The two branches "master" and "maint" are never rewound, and "next"
-usually will not be either (this automatically means the topics that have
-been merged into "next" are usually not rebased, and you can find the tip
-of topic branches you are interested in from the output of "git log
-next"). You should be able to safely build on top of them.
-
-After a feature release is made from "master", however, "next" will be
-rebuilt from the tip of "master" using the surviving topics. The commit
-that replaces the tip of the "next" will usually have the identical tree,
-but it will have different ancestry from the tip of "master".
-
-The "pu" (proposed updates) branch bundles all the remainder of topic
-branches. The "pu" branch, and topic branches that are only in "pu", are
-subject to rebasing in general. By the above definition of how "next"
-works, you can tell that this branch will contain quite experimental and
-obviously broken stuff.
-
-When a topic that was in "pu" proves to be in testable shape, it graduates
-to "next". I do this with:
+usually will not be either. After a feature release is made from
+"master", however, "next" will be rebuilt from the tip of "master"
+using the topics that didn't make the cut in the feature release.
- git checkout next
- git merge that-topic-branch
-
-Sometimes, an idea that looked promising turns out to be not so good and
-the topic can be dropped from "pu" in such a case.
-
-A topic that is in "next" is expected to be polished to perfection before
-it is merged to "master" (that's why "master" can be expected to stay more
-stable than any released version). Similarly to the above, I do it with
-this:
-
- git checkout master
- git merge that-topic-branch
- git branch -d that-topic-branch
-
-Note that being in "next" is not a guarantee to appear in the next release
-(being in "master" is such a guarantee, unless it is later found seriously
-broken and reverted), nor even in any future release. There even were
-cases that topics needed reverting a few commits in them before graduating
-to "master", or a topic that already was in "next" were entirely reverted
-from "next" because fatal flaws were found in them later.
+Note that being in "next" is not a guarantee to appear in the next
+release, nor even in any future release. There were cases that topics
+needed reverting a few commits in them before graduating to "master", or a
+topic that already was in "next" was reverted from "next" because fatal
+flaws were found in it after it was merged.
* Other people's trees, trusted lieutenants and credits.
shape. Especially I would like to thank the git list regulars whose help
I have relied on and expect to continue relying on heavily:
- - Linus on general design issues.
-
- - Linus, Shawn Pearce, Johannes Schindelin, Nicolas Pitre, René
- Scharfe, Jeff King, Jonathan Nieder, Johan Herland, Johannes Sixt,
- Sverre Rabbelier and Thomas Rast on general implementation issues
- and reviews on the mailing list.
+ - Linus Torvalds, Shawn Pearce, Johannes Schindelin, Nicolas Pitre,
+ René Scharfe, Jeff King, Jonathan Nieder, Johan Herland, Johannes
+ Sixt, Sverre Rabbelier, Michael J Gruber, Nguyễn Thái Ngọc Duy,
+ Ævar Arnfjörð Bjarmason and Thomas Rast on general design and
+ implementation issues and reviews on the mailing list.
- Shawn and Nicolas Pitre on pack issues.
projects / thirdparty / git.git / commitdiff
