@matheusbsbs / matheus-bagliano / commits / ae397f597b

MaintNotes 2007-02-16 edition

Junio C Hamano committed Apr 4, 2007 at 11:25 UTC ae397f597bfaf4e8beb9b56d533e54090bfeea92
1 file changed +212
MaintNotes new
+212
@@ -0,0 +1,212 @@
1 +It has been a while since I sent this message out the last time,
2 +so it may be a good time to send it with updates again. There
3 +seem to be some new people on the git list, especially now the
4 +big release is out.
5 +
6 +This message talks about how git.git is managed, and how you can
7 +work with it.
8 +
9 +
10 +* IRC and Mailing list
11 +
12 +Many active members of development community hang around on #git
13 +IRC channel. Its log is available at:
14 +
15 + http://colabti.de/irclogger/irclogger_logs/git
16 +
17 +[jc: Does anybody know a shortcut for "Today's" page on this
18 + site? It irritates me having to click the latest link on this
19 + page to get to the latest.]
20 +
21 +
22 +The development however is primarily done on this mailing list
23 +you are reading right now. If you have patches, please send
24 +them to the list, following Documentation/SubmittingPatches.
25 +
26 +I usually read all patches posted to the list, and follow almost
27 +all the discussions on the list, unless the topic is about an
28 +obscure corner that I do not personally use. But I am obviously
29 +not perfect. If you sent a patch that you did not hear from
30 +anybody for three days, that is a very good indication that it
31 +was dropped on the floor --- please do not hesitate to remind
32 +me.
33 +
34 +The list archive is available at a few public sites as well:
35 +
36 + http://marc.theaimsgroup.com/?l=git
37 + http://news.gmane.org/gmane.comp.version-control.git
38 +
39 +and some people seem to prefer to read it over NNTP:
40 +
41 + nntp://news.gmane.org/gmane.comp.version-control.git
42 +
43 +
44 +* Repositories, branches and documentation.
45 +
46 +My public git.git repository is at:
47 +
48 + git://git.kernel.org/pub/scm/git/git.git/
49 +
50 +This is mirrored at Pasky's site at
51 +
52 + git://repo.or.cz/git.git/
53 +
54 +but the first has a few hours mirroring delay after I publish
55 +updates, and the latter, being a mirror of former, lags behind
56 +it further. Immediately after I publish to the primary
57 +repository at kernel.org, I also push into an alternate here:
58 +
59 + git://repo.or.cz/alt-git.git/
60 +
61 +Impatient people would have better lack with the last one (but
62 +the last repository does not have "html", "man" and "todo"
63 +branches, described next).
64 +
65 +
66 +There are three branches in git.git repository that are not
67 +about the source tree of git: "todo", "html" and "man". The
68 +first one was meant to contain TODO list for me, but I am not
69 +good at maintaining such a list so it is not as often updated as
70 +it could/should be. It also contains some helper scripts I use
71 +to maintain git.
72 +
73 +The "html" and "man" are autogenerated documentation from the
74 +tip of the "master" branch; the tip of "html" is extracted to be
75 +visible at kernel.org at:
76 +
77 + http://www.kernel.org/pub/software/scm/git/docs/
78 +
79 +Starting from 1.5.0, the top-level documentation page has links
80 +to documentation of older releases.
81 +
82 +The script to maintain these two documentation branches are
83 +found in "todo" branch as dodoc.sh, if you are interested. It
84 +is a good demonstration of how to use an update hook to automate
85 +a task.
86 +
87 +There are four branches in git.git repository that track the
88 +source tree of git: "master", "maint", "next", and "pu".
89 +
90 +The "master" branch is meant to contain what are reasonably
91 +tested and ready to be used in a production setting. There
92 +could occasionally be minor breakages or brown paper bag bugs
93 +but they are not expected to be anything major. Every now and
94 +then, a "feature release" is cut from the tip of this branch and
95 +they typically are named with three dotted decimal digits. The
96 +last such release was v1.5.0 done on Feb 14th this year. The
97 +codename for that release is not "snog".
98 +
99 +Whenever a feature release is made, "maint" branch is forked off
100 +from "master" at that point. Obvious, safe and urgent fixes
101 +after a feature release are applied to this branch and
102 +maintenance releases are cut from it. The maintenance releases
103 +are typically named with four dotted decimal, named after the
104 +feature release they are updates to; the last such release was
105 +v1.4.4.4, and I am expecting to cut v1.5.0.1 sometime soon.
106 +Usually new development will never go to this branch. This
107 +branch is also merged into "master" to propagate the fixes
108 +forward.
109 +
110 +A trivial and safe enhancement goes directly on top of "master".
111 +A new development, either initiated by myself or more often by
112 +somebody who found his or her own itch to scratch, does not
113 +usually happen on "master", however. Instead, it is forked into
114 +a separate topic branch from the tip of "master", and first
115 +tested in isolation; I may make minimum fixups at this point.
116 +Usually there are a handful such topic branches that are running
117 +ahead of "master" in git.git repository. I do not publish the
118 +tip of these branches in my public repository, however, partly
119 +to keep the number of branches that downstream developers need
120 +to worry about and primarily because I am lazy.
121 +
122 +I judge the quality of topic branches, taking advices from the
123 +mailing list discussions. Some of them start out as "good idea
124 +but obviously is broken in some areas (e.g. breaks the existing
125 +testsuite)" and then with some more work (either by the original
126 +contributor or help from other people on the list) becomes "more
127 +or less done and can now be tested by wider audience". Luckily,
128 +most of them start out in the latter, better shape.
129 +
130 +The "next" branch is to merge and test topic branches in the
131 +latter category. In general it should always contain the tip of
132 +"master". They might not be quite production ready, but are
133 +expected to work more or less without major breakage. I usually
134 +use "next" version of git for my own work, so it cannot be
135 +_that_ broken to prevent me from pushing the changes out.
136 +The "next" branch is where new and exciting things take place.
137 +
138 +The above three branches, "master", "maint" and "next" are never
139 +rewound, so you should be able to safely track them (that means
140 +the topics that have been merged into "next" are not rebased).
141 +
142 +The "pu" (proposed updates) branch bundles all the remainder of
143 +topic branches. The "pu" branch, and topic branches that are
144 +only in "pu", are subject to rebasing in general.
145 +
146 +When a topic that was in "pu" proves to be in testable shape, it
147 +graduates to "next". I do this with:
148 +
149 + git checkout next
150 + git merge that-topic-branch
151 +
152 +Sometimes, an idea that looked promising turns out to be not so
153 +hot and the topic can be dropped from "pu" in such a case.
154 +
155 +A topic that is in "next" is expected to be tweaked and fixed to
156 +perfection before it is merged to "master". However, being in
157 +"next" is not a guarantee to appear in the next release (being
158 +in "master" is such a guarantee, unless it is later found
159 +seriously broken and reverted), or even in any future release.
160 +There even were cases that topics needed a few reverting before
161 +graduating to "master", or a topic that already was in "next"
162 +were reverted from "next" because fatal flaws were found in them
163 +later.
164 +
165 +Starting from v1.5.0, "master" and "maint" have release notes
166 +for the next release in Documentation/RelNotes-* files, so that
167 +I do not have to run around summarizing what happened just
168 +before the release.
169 +
170 +
171 +* Other people's trees, trusted lieutenants and credits.
172 +
173 +Documentation/SubmittingPatches outlines who your changes should
174 +be sent to. As described in contrib/README, I would delegate
175 +fixes and enhancements in contrib/ area to primary contributors
176 +of them.
177 +
178 +Although the following are included in git.git repository, they
179 +have their own authoritative repository and maintainers:
180 +
181 + git-gui/ -- this subdirectory comes from Shawn Pearce's git-gui
182 + project, which is found at:
183 +
184 + git://repo.or.cz/git-gui.git
185 +
186 + gitk -- this file is maintained by Paul Packerras, at:
187 +
188 + git://git.kernel.org/pub/scm/gitk/gitk.git
189 +
190 +I would like to thank everybody who helped to raise git into the
191 +current shape. Especially I would like to thank the git list
192 +regulars whose help I have relied on and expect to continue
193 +relying on heavily:
194 +
195 + - Linus on general design issues.
196 +
197 + - Linus, Shawn Pearce, Johannes Schindelin, Nicolas Pitre, and
198 + Rene Scharfe on general implementation issues.
199 +
200 + - Shawn and Nicolas Pitre on pack issues.
201 +
202 + - Martin Langhoff on cvsserver and cvsimport.
203 +
204 + - Paul Packerras on gitk.
205 +
206 + - Eric Wong on git-svn.
207 +
208 + - Jakub Narebski and Luben Tuikov on gitweb.
209 +
210 + - J. Bruce Fields on documentaton issues.
211 +
212 +