diff --git a/MaintNotes b/MaintNotes index de86827564..5d7243df2f 100644 --- a/MaintNotes +++ b/MaintNotes @@ -1,25 +1,30 @@ -Welcome to git community. +Welcome to git development community. -This message talks about how git.git is managed, and how you can work -with it. +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 -Many active members of development community hang around on #git +Members of the development community can sometimes be found on #git IRC channel on Freenode. Its log is available at: http://colabti.org/irclogger/irclogger_log/git -The development however is primarily done on the git mailing list -(git@vger.kernel.org). If you have patches, please send them to the -list, following Documentation/SubmittingPatches. +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". -I usually try to read all patches posted to the list, and follow -almost all the discussions on the list, unless the topic is about an -obscure corner that I do not personally use. But I am obviously not -perfect. If you sent a patch that you did not hear from anybody for -three days, that is a very good indication that it was dropped on the -floor --- please do not hesitate to remind me. +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. The list archive is available at a few public sites as well: @@ -58,137 +63,129 @@ 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 -in/cooking" messages these days. +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 kernel.org at: +The "html" and "man" are autogenerated 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 script to maintain these two documentation branches are -found in "todo" branch as dodoc.sh, if you are interested. It -is a good demonstration of how to use a post-update hook to -automate a task. +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 +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. +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. -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.6.4 done on Jul 29th 2009. You -can expect that the tip of the "master" branch is always more -stable than any of the released versions. +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.6.6 done on Dec 23rd 2009. 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.6.4.1. -New features never go to this branch. This branch is also +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.6.5.7. 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 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. +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 pushing the changes out. -The "next" branch is where new and exciting things take place. +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 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 track them. +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". An announcement will be made to warn -people about such a rebasing. +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. +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: +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. +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 tweaked and fixed to -perfection before it is merged to "master" (that's why "master" -can be expected to stay very stable). Similarly to the above, I -do it with this: +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 +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. * Other people's trees, trusted lieutenants and credits. -Documentation/SubmittingPatches outlines to whom your proposed -changes should be sent. As described in contrib/README, I would -delegate fixes and enhancements in contrib/ area to the primary -contributors of them. +Documentation/SubmittingPatches outlines to whom your proposed changes +should be sent. As described in contrib/README, I would delegate fixes +and enhancements in contrib/ area to the primary contributors of them. -Although the following are included in git.git repository, they -have their own authoritative repository and maintainers: +Although the following are included in git.git repository, they have their +own authoritative repository and maintainers: - git-gui/ comes from Shawn Pearce's git-gui project: @@ -198,16 +195,15 @@ have their own authoritative repository and maintainers: git://git.kernel.org/pub/scm/gitk/gitk.git -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: +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 and Johannes Sixt on general - implementation issues. + - Linus, Shawn Pearce, Johannes Schindelin, Nicolas Pitre, René + Scharfe, Jeff King and Johannes Sixt on general implementation + issues. - Shawn and Nicolas Pitre on pack issues. @@ -219,8 +215,8 @@ relying on heavily: - Simon Hausmann on git-p4. - - Jakub Narebski, Petr Baudis, Luben Tuikov, Giuseppe Bilotta - on gitweb. + - Jakub Narebski, Petr Baudis, Luben Tuikov, Giuseppe Bilotta on + gitweb. - J. Bruce Fields on documentation (and countless others for proofreading and fixing). @@ -232,13 +228,13 @@ relying on heavily: - David Aguilar for git-difftool. - - Johannes Schindelin, Johannes Sixt and others for their effort - to move things forward on the Windows front. + - Johannes Schindelin, Johannes Sixt and others for their effort to + move things forward on the Windows front. - People on non-Linux platforms for keeping their eyes on - portability; especially, Randal Schwartz, Theodore Ts'o, - Jason Riedy, Thomas Glanzmann, Brandon Casey, Jeff King, - Alex Riesen and countless others. + portability; especially, Randal Schwartz, Theodore Ts'o, Jason + Riedy, Thomas Glanzmann, Brandon Casey, Jeff King, Alex Riesen and + countless others. * This document