MaintNotes: cut cruft and add bug reporting section
Junio C Hamano
parent
cf98037ac2
commit
9f1017f641
215
MaintNotes
215
MaintNotes
|
|
@ -3,28 +3,27 @@ Welcome to git development community.
|
|||
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:
|
||||
|
||||
|
|
@ -41,8 +40,39 @@ gmane is often the easiest to follow by readers, like this:
|
|||
|
||||
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.
|
||||
|
||||
|
|
@ -64,119 +94,75 @@ Their gitweb interfaces are found at:
|
|||
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.
|
||||
source tree of git: "html", "man", and "todo".
|
||||
|
||||
The "html" and "man" are autogenerated documentation from the tip of the
|
||||
"master" branch; the tip of "html" is extracted to be visible at
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
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 "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.
|
||||
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.
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
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.
|
||||
|
|
@ -200,12 +186,11 @@ I would like to thank everybody who helped to raise git into the current
|
|||
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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue