@matheusbsbs / matheus-bagliano / commits / 9f1017f641

MaintNotes: cut cruft and add bug reporting section

Junio C Hamano committed Apr 25, 2011 at 14:03 UTC 9f1017f6414d81e9dc561c2cc627b6fcd05d57b2
1 file changed +103 -118
MaintNotes
+103 -118
@@ -3,28 +3,27 @@ Welcome to git development community.
3 This message is written by the maintainer and talks about how Git
4 project is managed, and how you can work with it.
5
6 -* IRC and Mailing list
6 +* Mailing list and the community
7
8 -Members of the development community can sometimes be found on #git
9 -IRC channel on Freenode. Its log is available at:
8 +The development is primarily done on the Git mailing list. Help
9 +requests, feature proposals, bug reports and patches should be sent to
10 +the list address <git@vger.kernel.org>. You don't have to be
11 +subscribed to send messages. The convention on the list is to keep
12 +everybody involved on Cc:, so it is unnecessary to ask "Please Cc: me,
13 +I am not subscribed".
14
11 - http://colabti.org/irclogger/irclogger_log/git
12 -
13 -The development is primarily done on the Git mailing list. If you have
14 -patches, please send them to the list address (git@vger.kernel.org).
15 -following Documentation/SubmittingPatches. You don't have to be
16 -subscribed to send messages there, and the convention is to Cc:
17 -everybody involved, so you don't even have to say "Please Cc: me, I am
18 -not subscribed".
15 +Before sending patches, please read Documentation/SubmittingPatches
16 +and Documentation/CodingGuidelines to familiarize yourself with the
17 +project convention.
18
19 If you sent a patch and you did not hear any response from anybody for
21 -several days, it could be that your patch was totally uninteresting, but
22 -it also is possible that it was simply lost in the noise. Please do not
23 -hesitate to send a reminder message politely in such a case. Messages
24 -getting lost in the noise is a sign that people involved don't have enough
25 -mental/time bandwidth to process them right at the moment, and it often
26 -helps to wait until the list traffic becomes calmer before sending such a
27 -reminder.
20 +several days, it could be that your patch was totally uninteresting,
21 +but it also is possible that it was simply lost in the noise. Please
22 +do not hesitate to send a reminder message in such a case. Messages
23 +getting lost in the noise is a sign that people involved don't have
24 +enough mental/time bandwidth to process them right at the moment, and
25 +it often helps to wait until the list traffic becomes calmer before
26 +sending such a reminder.
27
28 The list archive is available at a few public sites as well:
29
@@ -41,8 +40,39 @@ gmane is often the easiest to follow by readers, like this:
40
41 http://thread.gmane.org/gmane.comp.version-control.git/27/focus=217
42
44 -as it also allows people who subscribe to the mailing list as
45 -gmane newsgroup to "jump to" the article.
43 +as it also allows people who subscribe to the mailing list as gmane
44 +newsgroup to "jump to" the article.
45 +
46 +Some members of the development community can sometimes also be found
47 +on the #git IRC channel on Freenode. Its log is available at:
48 +
49 + http://colabti.org/irclogger/irclogger_log/git
50 +
51 +* Reporting bugs
52 +
53 +When you think git does not behave as you expect, please do not stop your
54 +bug report with just "git does not work". "I tried to do X but it did not
55 +work" is not much better, neither is "I tried to do X and git did Y, which
56 +is broken". It often is that what you expect is _not_ what other people
57 +expect, and chances are that what you expect is very different from what
58 +people who have worked on git have expected (otherwise, the behavior
59 +would have been changed to match that expectation long time ago).
60 +
61 +Please remember to always state
62 +
63 + - what you wanted to do;
64 +
65 + - what you did (the version of git and the command sequence to reproduce
66 + the behavior);
67 +
68 + - what you saw happen;
69 +
70 + - what you expected to see; and
71 +
72 + - how the last two are different.
73 +
74 +See http://www.chiark.greenend.org.uk/~sgtatham/bugs.html for further
75 +hints.
76
77 * Repositories, branches and documentation.
78
@@ -64,119 +94,75 @@ Their gitweb interfaces are found at:
94 http://repo.or.cz/w/alt-git.git
95
96 There are three branches in git.git repository that are not about the
67 -source tree of git: "todo", "html" and "man". The first one was meant to
68 -contain TODO list for me, but I am not good at maintaining such a list and
69 -it is in an abandoned state. The branch mostly is used to keep some
70 -helper scripts I use to maintain git and the regular "What's cooking"
71 -messages these days.
72 -
73 -The "html" and "man" are autogenerated documentation from the tip of the
74 -"master" branch; the tip of "html" is extracted to be visible at
97 +source tree of git: "html", "man", and "todo".
98 +
99 +The "html" and "man" are auto-generated documentation from the tip of
100 +the "master" branch; the tip of "html" is extracted to be visible at
101 kernel.org at:
102
103 http://www.kernel.org/pub/software/scm/git/docs/
104
79 -The above URL is the top-level documentation page, and it has
80 -links to documentation of older releases.
105 +The above URL is the top-level documentation page, and it has links to
106 +documentation of older releases.
107
82 -The script to maintain these two documentation branches are found in the
83 -"todo" branch as dodoc.sh, if you are interested. It is a demonstration
84 -of how to use a post-update hook to automate a task after pushing into a
108 +The "todo" branch was originally meant to contain a TODO list for me,
109 +but is mostly used to keep some helper scripts I use to maintain git.
110 +For example, the script to maintain the two documentation branches are
111 +found there as dodoc.sh, which may be a good demonstration of how to
112 +use a post-update hook to automate a task after pushing into a
113 repository.
114
115 There are four branches in git.git repository that track the source tree
88 -of git: "master", "maint", "next", and "pu". I may add more maintenance
89 -branches (e.g. "maint-1.6.3") if we have hugely backward incompatible
90 -feature updates in the future to keep an older release alive; I may not,
91 -but the distributed nature of git means any volunteer can run a
92 -stable-tree like that herself.
116 +of git: "master", "maint", "next", and "pu".
117
118 The "master" branch is meant to contain what are very well tested and
95 -ready to be used in a production setting. There could occasionally be
96 -minor breakages or brown paper bag bugs but they are not expected to be
97 -anything major, and more importantly quickly and trivially fixable. Every
98 -now and then, a "feature release" is cut from the tip of this branch and
99 -they typically are named with three dotted decimal digits. The last such
100 -release was 1.7.4 done on Jan 30, 2011. You can expect that the tip of
101 -the "master" branch is always more stable than any of the released
102 -versions.
119 +ready to be used in a production setting. Every now and then, a "feature
120 +release" is cut from the tip of this branch and they typically are named
121 +with three dotted decimal digits. The last such release was 1.7.5 done on
122 +Apr 24, 2011. You can expect that the tip of the "master" branch is
123 +always more stable than any of the released versions.
124
125 Whenever a feature release is made, "maint" branch is forked off from
126 "master" at that point. Obvious, safe and urgent fixes after a feature
127 release are applied to this branch and maintenance releases are cut from
128 it. The maintenance releases are named with four dotted decimal, named
129 after the feature release they are updates to; the last such release was
109 -1.7.3.5. New features never go to this branch. This branch is also
130 +1.7.4.5. New features never go to this branch. This branch is also
131 merged into "master" to propagate the fixes forward.
132
112 -A trivial and safe enhancement goes directly on top of "master". A new
113 -development, either initiated by myself or more often by somebody who
114 -found his or her own itch to scratch, does not usually happen on "master",
115 -however. Instead, a separate topic branch is forked from the tip of
116 -"master", and it first is tested in isolation; I may make minimum fixups
117 -at this point. Usually there are a handful such topic branches that are
118 -running ahead of "master" in git.git repository. I do not publish the tip
119 -of these branches in my public repository, however, partly to keep the
120 -number of branches that downstream developers need to worry about low, and
121 -primarily because I am lazy.
122 -
123 -The quality of topic branches are judged primarily by the mailing list
124 -discussions. Some of them start out as "good idea but obviously is broken
125 -in some areas (e.g. breaks the existing testsuite)" and then with some
126 -more work (either by the original contributor's effort or help from other
127 -people on the list) becomes "more or less done and can now be tested by
128 -wider audience". Luckily, most of them start out in the latter, better
129 -shape.
130 -
131 -The "next" branch is to merge and test topic branches in the latter
132 -category. In general, the branch always contains the tip of "master". It
133 -might not be quite rock-solid production ready, but is expected to work
134 -more or less without major breakage. I usually use "next" version of git
135 -for my own work, so it cannot be _that_ broken to prevent me from
136 -integrating and pushing the changes out. The "next" branch is where new
137 -and exciting things take place.
133 +A new development does not usually happen on "master". When you send a
134 +series of patches, after review on the mailing list, a separate topic
135 +branch is forked from the tip of "master" and your patches are queued
136 +there, and kept out of "master" while people test it out. The quality of
137 +topic branches are judged primarily by the mailing list discussions.
138 +
139 +Topic branches that are in good shape are merged to the "next" branch. In
140 +general, the "next" branch always contains the tip of "master". It might
141 +not be quite rock-solid production ready, but is expected to work more or
142 +less without major breakage. The "next" branch is where new and exciting
143 +things take place. A topic that is in "next" is expected to be polished to
144 +perfection before it is merged to "master" (that's why "master" can be
145 +expected to stay more stable than any released version).
146 +
147 +The "pu" (proposed updates) branch bundles all the remaining topic
148 +branches. The topics on the branch are not complete, well tested, nor well
149 +documented and need further work. When a topic that was in "pu" proves to
150 +be in testable shape, it is merged to "next".
151 +
152 +You can run "git log --first-parent master..pu" to see what topics are
153 +currently in flight. Sometimes, an idea that looked promising turns out
154 +to be not so good and the topic can be dropped from "pu" in such a case.
155
156 The two branches "master" and "maint" are never rewound, and "next"
140 -usually will not be either (this automatically means the topics that have
141 -been merged into "next" are usually not rebased, and you can find the tip
142 -of topic branches you are interested in from the output of "git log
143 -next"). You should be able to safely build on top of them.
144 -
145 -After a feature release is made from "master", however, "next" will be
146 -rebuilt from the tip of "master" using the surviving topics. The commit
147 -that replaces the tip of the "next" will usually have the identical tree,
148 -but it will have different ancestry from the tip of "master".
149 -
150 -The "pu" (proposed updates) branch bundles all the remainder of topic
151 -branches. The "pu" branch, and topic branches that are only in "pu", are
152 -subject to rebasing in general. By the above definition of how "next"
153 -works, you can tell that this branch will contain quite experimental and
154 -obviously broken stuff.
155 -
156 -When a topic that was in "pu" proves to be in testable shape, it graduates
157 -to "next". I do this with:
157 +usually will not be either. After a feature release is made from
158 +"master", however, "next" will be rebuilt from the tip of "master"
159 +using the topics that didn't make the cut in the feature release.
160
159 - git checkout next
160 - git merge that-topic-branch
161 -
162 -Sometimes, an idea that looked promising turns out to be not so good and
163 -the topic can be dropped from "pu" in such a case.
164 -
165 -A topic that is in "next" is expected to be polished to perfection before
166 -it is merged to "master" (that's why "master" can be expected to stay more
167 -stable than any released version). Similarly to the above, I do it with
168 -this:
169 -
170 - git checkout master
171 - git merge that-topic-branch
172 - git branch -d that-topic-branch
173 -
174 -Note that being in "next" is not a guarantee to appear in the next release
175 -(being in "master" is such a guarantee, unless it is later found seriously
176 -broken and reverted), nor even in any future release. There even were
177 -cases that topics needed reverting a few commits in them before graduating
178 -to "master", or a topic that already was in "next" were entirely reverted
179 -from "next" because fatal flaws were found in them later.
161 +Note that being in "next" is not a guarantee to appear in the next
162 +release, nor even in any future release. There were cases that topics
163 +needed reverting a few commits in them before graduating to "master", or a
164 +topic that already was in "next" was reverted from "next" because fatal
165 +flaws were found in it after it was merged.
166
167
168 * 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
186 shape. Especially I would like to thank the git list regulars whose help
187 I have relied on and expect to continue relying on heavily:
188
203 - - Linus on general design issues.
204 -
205 - - Linus, Shawn Pearce, Johannes Schindelin, Nicolas Pitre, René
206 - Scharfe, Jeff King, Jonathan Nieder, Johan Herland, Johannes Sixt,
207 - Sverre Rabbelier and Thomas Rast on general implementation issues
208 - and reviews on the mailing list.
189 + - Linus Torvalds, Shawn Pearce, Johannes Schindelin, Nicolas Pitre,
190 + René Scharfe, Jeff King, Jonathan Nieder, Johan Herland, Johannes
191 + Sixt, Sverre Rabbelier, Michael J Gruber, Nguyễn Thái Ngọc Duy,
192 + Ævar Arnfjörð Bjarmason and Thomas Rast on general design and
193 + implementation issues and reviews on the mailing list.
194
195 - Shawn and Nicolas Pitre on pack issues.
196