caea32db2c · matheusbsbs/matheus-bagliano

@@ -1,25 +1,30 @@

1 -Welcome to git community.

1 +Welcome to git development community.

2

3 -This message talks about how git.git is managed, and how you can work

4 -with it.

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

7

8 -Many active members of development community hang around on #git

8 +Members of the development community can sometimes be found on #git

9 IRC channel on Freenode. Its log is available at:

10

11 http://colabti.org/irclogger/irclogger_log/git

12

13 -The development however is primarily done on the git mailing list

14 -(git@vger.kernel.org). If you have patches, please send them to the

15 -list, following Documentation/SubmittingPatches.

16 -

17 -I usually try to read all patches posted to the list, and follow

18 -almost all the discussions on the list, unless the topic is about an

19 -obscure corner that I do not personally use. But I am obviously not

20 -perfect. If you sent a patch that you did not hear from anybody for

21 -three days, that is a very good indication that it was dropped on the

22 -floor --- please do not hesitate to remind me.

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".

19 +

20 +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.

28

29 The list archive is available at a few public sites as well:

30

@@ -58,137 +63,129 @@ Their gitweb interfaces are found at:

63 http://repo.or.cz/w/alt-git.git

64

65 There are three branches in git.git repository that are not about the

61 -source tree of git: "todo", "html" and "man". The first one was meant

62 -to contain TODO list for me, but I am not good at maintaining such a

63 -list and it is in an abandoned state. The branch mostly is used to

64 -keep some helper scripts I use to maintain git and the regular "What's

65 -in/cooking" messages these days.

66 +source tree of git: "todo", "html" and "man". The first one was meant to

67 +contain TODO list for me, but I am not good at maintaining such a list and

68 +it is in an abandoned state. The branch mostly is used to keep some

69 +helper scripts I use to maintain git and the regular "What's cooking"

70 +messages these days.

71

67 -The "html" and "man" are autogenerated documentation from the

68 -tip of the "master" branch; the tip of "html" is extracted to be

69 -visible at kernel.org at:

72 +The "html" and "man" are autogenerated documentation from the tip of the

73 +"master" branch; the tip of "html" is extracted to be visible at

74 +kernel.org at:

75

76 http://www.kernel.org/pub/software/scm/git/docs/

77

78 The above URL is the top-level documentation page, and it has

79 links to documentation of older releases.

80

76 -The script to maintain these two documentation branches are

77 -found in "todo" branch as dodoc.sh, if you are interested. It

78 -is a good demonstration of how to use a post-update hook to

79 -automate a task.

80 -

81 -There are four branches in git.git repository that track the

82 -source tree of git: "master", "maint", "next", and "pu". I may

83 -add more maintenance branches (e.g. "maint-1.6.3") if we have

84 -hugely backward incompatible feature updates in the future to keep

85 -an older release alive; I may not, but the distributed nature of

86 -git means any volunteer can run a stable-tree like that herself.

87 -

88 -The "master" branch is meant to contain what are very well

89 -tested and ready to be used in a production setting. There

90 -could occasionally be minor breakages or brown paper bag bugs

91 -but they are not expected to be anything major, and more

92 -importantly quickly and trivially fixable. Every now and

93 -then, a "feature release" is cut from the tip of this branch and

94 -they typically are named with three dotted decimal digits. The

95 -last such release was 1.6.4 done on Jul 29th 2009. You

96 -can expect that the tip of the "master" branch is always more

97 -stable than any of the released versions.

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 named with four dotted decimal, named after the feature

104 -release they are updates to; the last such release was 1.6.4.1.

105 -New features never go to this branch. This branch is also

81 +The script to maintain these two documentation branches are found in the

82 +"todo" branch as dodoc.sh, if you are interested. It is a demonstration

83 +of how to use a post-update hook to automate a task after pushing into a

84 +repository.

85 +

86 +There are four branches in git.git repository that track the source tree

87 +of git: "master", "maint", "next", and "pu". I may add more maintenance

88 +branches (e.g. "maint-1.6.3") if we have hugely backward incompatible

89 +feature updates in the future to keep an older release alive; I may not,

90 +but the distributed nature of git means any volunteer can run a

91 +stable-tree like that herself.

92 +

93 +The "master" branch is meant to contain what are very well tested and

94 +ready to be used in a production setting. There could occasionally be

95 +minor breakages or brown paper bag bugs but they are not expected to be

96 +anything major, and more importantly quickly and trivially fixable. Every

97 +now and then, a "feature release" is cut from the tip of this branch and

98 +they typically are named with three dotted decimal digits. The last such

99 +release was 1.6.6 done on Dec 23rd 2009. You can expect that the tip of

100 +the "master" branch is always more stable than any of the released

101 +versions.

102 +

103 +Whenever a feature release is made, "maint" branch is forked off from

104 +"master" at that point. Obvious, safe and urgent fixes after a feature

105 +release are applied to this branch and maintenance releases are cut from

106 +it. The maintenance releases are named with four dotted decimal, named

107 +after the feature release they are updates to; the last such release was

108 +1.6.5.7. New features never go to this branch. This branch is also

109 merged into "master" to propagate the fixes forward.

110

108 -A trivial and safe enhancement goes directly on top of "master".

109 -A new development, either initiated by myself or more often by

110 -somebody who found his or her own itch to scratch, does not

111 -usually happen on "master", however. Instead, a separate topic

112 -branch is forked from the tip of "master", and it first is

113 -tested in isolation; I may make minimum fixups at this point.

114 -Usually there are a handful such topic branches that are running

115 -ahead of "master" in git.git repository. I do not publish the

116 -tip of these branches in my public repository, however, partly

117 -to keep the number of branches that downstream developers need

118 -to worry about low, and primarily because I am lazy.

111 +A trivial and safe enhancement goes directly on top of "master". A new

112 +development, either initiated by myself or more often by somebody who

113 +found his or her own itch to scratch, does not usually happen on "master",

114 +however. Instead, a separate topic branch is forked from the tip of

115 +"master", and it first is tested in isolation; I may make minimum fixups

116 +at this point. Usually there are a handful such topic branches that are

117 +running ahead of "master" in git.git repository. I do not publish the tip

118 +of these branches in my public repository, however, partly to keep the

119 +number of branches that downstream developers need to worry about low, and

120 +primarily because I am lazy.

121

122 The quality of topic branches are judged primarily by the mailing list

121 -discussions. Some of them start out as "good idea but obviously is

122 -broken in some areas (e.g. breaks the existing testsuite)" and then

123 -with some more work (either by the original contributor's effort or

124 -help from other people on the list) becomes "more or less done and can

125 -now be tested by wider audience". Luckily, most of them start out in

126 -the latter, better shape.

127 -

128 -The "next" branch is to merge and test topic branches in the

129 -latter category. In general, the branch always contains the tip

130 -of "master". It might not be quite rock-solid production ready,

131 -but is expected to work more or less without major breakage. I

132 -usually use "next" version of git for my own work, so it cannot

133 -be _that_ broken to prevent me from pushing the changes out.

134 -The "next" branch is where new and exciting things take place.

135 -

136 -The two branches "master" and "maint" are never rewound, and

137 -"next" usually will not be either (this automatically means the

138 -topics that have been merged into "next" are usually not

139 -rebased, and you can find the tip of topic branches you are

140 -interested in from the output of "git log next"). You should be

141 -able to safely track them.

142 -

143 -After a feature release is made from "master", however, "next"

144 -will be rebuilt from the tip of "master" using the surviving

145 -topics. The commit that replaces the tip of the "next" will

146 -usually have the identical tree, but it will have different ancestry

147 -from the tip of "master". An announcement will be made to warn

148 -people about such a rebasing.

149 -

150 -The "pu" (proposed updates) branch bundles all the remainder of

151 -topic branches. The "pu" branch, and topic branches that are

152 -only in "pu", are subject to rebasing in general. By the above

153 -definition of how "next" works, you can tell that this branch

154 -will contain quite experimental and obviously broken stuff.

155 -

156 -When a topic that was in "pu" proves to be in testable shape, it

157 -graduates to "next". I do this with:

123 +discussions. Some of them start out as "good idea but obviously is broken

124 +in some areas (e.g. breaks the existing testsuite)" and then with some

125 +more work (either by the original contributor's effort or help from other

126 +people on the list) becomes "more or less done and can now be tested by

127 +wider audience". Luckily, most of them start out in the latter, better

128 +shape.

129 +

130 +The "next" branch is to merge and test topic branches in the latter

131 +category. In general, the branch always contains the tip of "master". It

132 +might not be quite rock-solid production ready, but is expected to work

133 +more or less without major breakage. I usually use "next" version of git

134 +for my own work, so it cannot be _that_ broken to prevent me from

135 +integrating and pushing the changes out. The "next" branch is where new

136 +and exciting things take place.

137 +

138 +The two branches "master" and "maint" are never rewound, and "next"

139 +usually will not be either (this automatically means the topics that have

140 +been merged into "next" are usually not rebased, and you can find the tip

141 +of topic branches you are interested in from the output of "git log

142 +next"). You should be able to safely build on top of them.

143 +

144 +After a feature release is made from "master", however, "next" will be

145 +rebuilt from the tip of "master" using the surviving topics. The commit

146 +that replaces the tip of the "next" will usually have the identical tree,

147 +but it will have different ancestry from the tip of "master".

148 +

149 +The "pu" (proposed updates) branch bundles all the remainder of topic

150 +branches. The "pu" branch, and topic branches that are only in "pu", are

151 +subject to rebasing in general. By the above definition of how "next"

152 +works, you can tell that this branch will contain quite experimental and

153 +obviously broken stuff.

154 +

155 +When a topic that was in "pu" proves to be in testable shape, it graduates

156 +to "next". I do this with:

157

158 git checkout next

159 git merge that-topic-branch

160

162 -Sometimes, an idea that looked promising turns out to be not so

163 -good and the topic can be dropped from "pu" in such a case.

161 +Sometimes, an idea that looked promising turns out to be not so good and

162 +the topic can be dropped from "pu" in such a case.

163

165 -A topic that is in "next" is expected to be tweaked and fixed to

166 -perfection before it is merged to "master" (that's why "master"

167 -can be expected to stay very stable). Similarly to the above, I

168 -do it with this:

164 +A topic that is in "next" is expected to be polished to perfection before

165 +it is merged to "master" (that's why "master" can be expected to stay more

166 +stable than any released version). Similarly to the above, I do it with

167 +this:

168

169 git checkout master

170 git merge that-topic-branch

171 git branch -d that-topic-branch

172

174 -Note that being in "next" is not a guarantee to appear in the

175 -next release (being in "master" is such a guarantee, unless it

176 -is later found seriously broken and reverted), nor even in any

177 -future release. There even were cases that topics needed

178 -reverting a few commits in them before graduating to "master",

179 -or a topic that already was in "next" were entirely reverted

173 +Note that being in "next" is not a guarantee to appear in the next release

174 +(being in "master" is such a guarantee, unless it is later found seriously

175 +broken and reverted), nor even in any future release. There even were

176 +cases that topics needed reverting a few commits in them before graduating

177 +to "master", or a topic that already was in "next" were entirely reverted

178 from "next" because fatal flaws were found in them later.

179

180

181 * Other people's trees, trusted lieutenants and credits.

182

185 -Documentation/SubmittingPatches outlines to whom your proposed

186 -changes should be sent. As described in contrib/README, I would

187 -delegate fixes and enhancements in contrib/ area to the primary

188 -contributors of them.

183 +Documentation/SubmittingPatches outlines to whom your proposed changes

184 +should be sent. As described in contrib/README, I would delegate fixes

185 +and enhancements in contrib/ area to the primary contributors of them.

186

190 -Although the following are included in git.git repository, they

191 -have their own authoritative repository and maintainers:

187 +Although the following are included in git.git repository, they have their

188 +own authoritative repository and maintainers:

189

190 - git-gui/ comes from Shawn Pearce's git-gui project:

191

@@ -198,16 +195,15 @@ have their own authoritative repository and maintainers:

195

196 git://git.kernel.org/pub/scm/gitk/gitk.git

197

201 -I would like to thank everybody who helped to raise git into the

202 -current shape. Especially I would like to thank the git list

203 -regulars whose help I have relied on and expect to continue

204 -relying on heavily:

198 +I would like to thank everybody who helped to raise git into the current

199 +shape. Especially I would like to thank the git list regulars whose help

200 +I have relied on and expect to continue relying on heavily:

201

202 - Linus on general design issues.

203

208 - - Linus, Shawn Pearce, Johannes Schindelin, Nicolas Pitre,

209 - René Scharfe, Jeff King and Johannes Sixt on general

210 - implementation issues.

204 + - Linus, Shawn Pearce, Johannes Schindelin, Nicolas Pitre, René

205 + Scharfe, Jeff King and Johannes Sixt on general implementation

206 + issues.

207

208 - Shawn and Nicolas Pitre on pack issues.

209

@@ -219,8 +215,8 @@ relying on heavily:

215

216 - Simon Hausmann on git-p4.

217

222 - - Jakub Narebski, Petr Baudis, Luben Tuikov, Giuseppe Bilotta

223 - on gitweb.

218 + - Jakub Narebski, Petr Baudis, Luben Tuikov, Giuseppe Bilotta on

219 + gitweb.

220

221 - J. Bruce Fields on documentation (and countless others for

222 proofreading and fixing).

@@ -232,13 +228,13 @@ relying on heavily:

228

229 - David Aguilar for git-difftool.

230

235 - - Johannes Schindelin, Johannes Sixt and others for their effort

236 - to move things forward on the Windows front.

231 + - Johannes Schindelin, Johannes Sixt and others for their effort to

232 + move things forward on the Windows front.

233

234 - People on non-Linux platforms for keeping their eyes on

239 - portability; especially, Randal Schwartz, Theodore Ts'o,

240 - Jason Riedy, Thomas Glanzmann, Brandon Casey, Jeff King,

241 - Alex Riesen and countless others.

235 + portability; especially, Randal Schwartz, Theodore Ts'o, Jason

236 + Riedy, Thomas Glanzmann, Brandon Casey, Jeff King, Alex Riesen and

237 + countless others.

238

239 * This document

240

MaintNotes: post 1.6.6