MaintNotes 2007-02-16 edition

new file mode 100644 index 0000000000..687e0aa4cb --- /dev/null +++ b/MaintNotes @@ -0,0 +1,212 @@ +It has been a while since I sent this message out the last time, +so it may be a good time to send it with updates again. There +seem to be some new people on the git list, especially now the +big release is out. + +This message talks about how git.git is managed, and how you can +work with it. + + +* IRC and Mailing list + +Many active members of development community hang around on #git +IRC channel. Its log is available at: + + http://colabti.de/irclogger/irclogger_logs/git + +[jc: Does anybody know a shortcut for "Today's" page on this + site? It irritates me having to click the latest link on this + page to get to the latest.] + + +The development however is primarily done on this mailing list +you are reading right now. If you have patches, please send +them to the list, following Documentation/SubmittingPatches. + +I usually 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. + +The list archive is available at a few public sites as well: + + http://marc.theaimsgroup.com/?l=git + http://news.gmane.org/gmane.comp.version-control.git + +and some people seem to prefer to read it over NNTP: + + nntp://news.gmane.org/gmane.comp.version-control.git + + +* Repositories, branches and documentation. + +My public git.git repository is at: + + git://git.kernel.org/pub/scm/git/git.git/ + +This is mirrored at Pasky's site at + + git://repo.or.cz/git.git/ + +but the first has a few hours mirroring delay after I publish +updates, and the latter, being a mirror of former, lags behind +it further. Immediately after I publish to the primary +repository at kernel.org, I also push into an alternate here: + + git://repo.or.cz/alt-git.git/ + +Impatient people would have better lack with the last one (but +the last repository does not have "html", "man" and "todo" +branches, described next). + + +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 so it is not as often updated as +it could/should be. It also contains some helper scripts I use +to maintain git. + +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/ + +Starting from 1.5.0, the top-level documentation page 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 an update hook to automate +a task. + +There are four branches in git.git repository that track the +source tree of git: "master", "maint", "next", and "pu". + +The "master" branch is meant to contain what are reasonably +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. 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 v1.5.0 done on Feb 14th this year. The +codename for that release is not "snog". + +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 typically named with four dotted decimal, named after the +feature release they are updates to; the last such release was +v1.4.4.4, and I am expecting to cut v1.5.0.1 sometime soon. +Usually new development will 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, it is forked into +a separate topic branch from the tip of "master", and first +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 and primarily because I am lazy. + +I judge the quality of topic branches, taking advices from 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 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 it should always contain the tip of +"master". They might not be quite production ready, but are +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 above three branches, "master", "maint" and "next" are never +rewound, so you should be able to safely track them (that means +the topics that have been merged into "next" are not rebased). + +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. + +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 +hot 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". However, 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), or even in any future release. +There even were cases that topics needed a few reverting before +graduating to "master", or a topic that already was in "next" +were reverted from "next" because fatal flaws were found in them +later. + +Starting from v1.5.0, "master" and "maint" have release notes +for the next release in Documentation/RelNotes-* files, so that +I do not have to run around summarizing what happened just +before the release. + + +* Other people's trees, trusted lieutenants and credits. + +Documentation/SubmittingPatches outlines who your changes should +be sent to. As described in contrib/README, I would delegate +fixes and enhancements in contrib/ area to primary contributors +of them. + +Although the following are included in git.git repository, they +have their own authoritative repository and maintainers: + + git-gui/ -- this subdirectory comes from Shawn Pearce's git-gui + project, which is found at: + + git://repo.or.cz/git-gui.git + + gitk -- this file is maintained by Paul Packerras, at: + + 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: + + - Linus on general design issues. + + - Linus, Shawn Pearce, Johannes Schindelin, Nicolas Pitre, and + Rene Scharfe on general implementation issues. + + - Shawn and Nicolas Pitre on pack issues. + + - Martin Langhoff on cvsserver and cvsimport. + + - Paul Packerras on gitk. + + - Eric Wong on git-svn. + + - Jakub Narebski and Luben Tuikov on gitweb. + + - J. Bruce Fields on documentaton issues. + +