/[muddleftpd]/muddleftpd/Developer.txt
ViewVC logotype

Contents of /muddleftpd/Developer.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.4 - (show annotations) (download)
Mon Nov 3 13:35:00 2003 UTC (20 years, 5 months ago) by ganneff
Branch: MAIN
CVS Tags: HEAD
Branch point for: dev-rugger-nat, dev-ganneff-autotools
Changes since 1.3: +54 -9 lines
File MIME type: text/plain
Hints about merging/branching

1 Muddleftpd Developer Guidelines
2
3 This is: $Revision: 1.3 $.
4
5 [Note before: That text is assembled from different other guidelines I
6 read and some talks I had with other people.]
7
8 Contents
9
10 1.0 Copyright issues
11 1.1 Preface
12 1.2 CVS Branches
13 1.2.1 Branch management / Merging
14 1.3 Muddleftpd Releases
15 1.4 Security Updates, Important Bugfixes
16 1.5 ChangeLog Entries and CVS commit messages (log messages)
17 1.6 Code Submission if you are not a developer of Muddleftpd
18 1.7 How to become a developer
19
20
21 1.0 Copyright issues
22 Muddleftpd is developed under the GNU GPL license. Every code you
23 write/add to Muddleftpd has to be under the same license.
24 Every source file has to include the following lines at the top of the
25 file (you may change the comment style if needed):
26
27 /* FILENAME SHORT DESCRIPTION OF THE FILE
28
29 Copyright (C) 2002 Muddleftpd Team, http://www.nongnu.org/muddleftpd/
30
31 This program is free software; you can redistribute it and/or modify
32 it under the terms of the GNU General Public License as published by
33 the Free Software Foundation; either version 2, or (at your option)
34 any later version.
35
36 This program is distributed in the hope that it will be useful,
37 but WITHOUT ANY WARRANTY; without even the implied warranty of
38 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
39 GNU General Public License for more details.
40
41 You should have received a copy of the GNU General Public License
42 along with this program; if not, write to the Free Software
43 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
44 */
45
46
47
48 1.1 Preface
49
50 So that we can all work together in the most productive way, all
51 developers working on the code in CVS should follow the following
52 guidelines.
53
54 - You break it, you fix it. If you break something that was working
55 before you checked in your code, it's your responsebility to get
56 it working again. If you ask the other developers real nicely,
57 maybe they'll help you, but it is your responsability.
58
59 - Try to keep all your changes limited to the specific area you are
60 working on.
61
62 - Peoples interests change. Workloads change. So if you have code
63 for a task you are working on that is an improvement on what is
64 in CVS already, feel good about checking it in. If it doesnt break
65 anything, and adds/fixes something, it's a good thing to add to
66 the repository.
67
68 If you're working on something complex, and you want something
69 committed as an intermediate step, then it might be okay to commit
70 what you have. But try not to commit anything that is completely
71 broken. At minimum, check in something that is partially working,
72 with clear comments about "this isnt working yet, but this is what
73 I'm in the process of doing to get there".
74
75 - Write good cvs commit messages. Not just "modified" or blank lines.
76 It will be used for the ChangeLog, so it should really show what you
77 have done. A URL with good hints for ChangeLog entries is
78 http://www.red-bean.com/cvs2cl/changelogs.html
79 If you follow that as close as possible for your commit message
80 everything is fine.
81
82
83 1.2 CVS Branches
84
85 The Muddleftpd CVS repository has one primary tree, called MAIN. They
86 can be 0 to many branches used for quality control and developing new
87 features.
88 Note: All branch identifiers and tag names starting with release_ are
89 reserved and only used to indicate different release versions.
90
91 MAIN
92 This tree is under full control of Beau Kuiper. If you want to
93 change things here you have to get his OK first. That is to ensure
94 the quality and security of muddleftpd because all code added here
95 has to be fully reviewed. This tree will be branched to create new
96 releases and everyone that commits here (after the OK) has to make
97 sure HE DOESNT BREAK IT.
98
99 release_*
100 These branches are under control of Joerg Jaspert. He is the only
101 one who makes new releases. * is replaced with some information, see
102 1.3 below.
103 Such a branch is the place to fix bugs in a released version. See
104 below for more about that.
105
106 dev_NICK_feature
107 Every developer is allowed to create a branch within the
108 repository. Just replace NICK with the nick you have on Savannah and
109 feature with the feature you want to develop in that branch. That
110 way everyone knows whats going on with a particular branch.
111 He is then fully responsible for that branch, so if you want to work
112 on anothers developers branch talk to him first.
113 Developers can use that to work on new features/enhancements without
114 breaking the MAIN tree of muddleftpd and without the rules that are
115 for that tree.
116 Example: If you want to work on IPV6 support you create a branch
117 called something like 'ipv6' and do your work in it. Every then and
118 now you look at MAIN if there are interesting changes and merge them
119 into your branch if you like them. After a while you are finished
120 and at the point where you can say "Yes, its stable and good enough
121 for MAIN". Then you "freeze" this tree, eg. stop working on it and
122 telling all other that its frozen and coordinate with Beau to get it
123 merged into MAIN. Then you only commit things into that branch that
124 are needed to get it accepted into MAIN, and after all things are
125 sorted out you and Beau merge it into MAIN. Voila, a new feature is
126 there without breaking of our MAIN line. :)
127
128 If you ever create a branch and find out later that you dont need it,
129 you can remove that branch from the repository. The project admins are
130 allowed to do that for dead branches that arent used for longer then 2
131 months to keep the repository clean.
132 But please never remove a branch that has development work in it, even
133 if it is not used at the moment or looks like it never will again. It
134 may contain important source changes/ ways to solve a problem we can
135 use at a later time.
136
137 1.2.1 Branch management / Merging
138
139 Ok, sometimes you may want to create a branch or merge a branch with
140 MAIN (after Beau said yes to the changes). Some small hints for that are
141 listed below.
142 First to create the branch you want to work in. Its done with
143
144 cvs tag -b dev-developername-feature
145
146 That creates the branch, see above in 1.2 for the naming convention.
147 After that you NEED to do a
148
149 cvs update -r dev-developername-feature
150
151 to get your local copy to recognize the branch. If not you would still
152 work in MAIN and thats not what you want.
153
154 Now, for the merge. Its simple. You need a checkout of the latest
155 Version of the MAIN revisions. In that directory you execute
156
157 cvs update -j dev-developername-feature
158
159 to merge your changes with MAIN. That tries to merge all your changes,
160 but maybe there is a conflict. You then need to resolv that conflict
161 before you commit the changes, of course. After you resolved all
162 conflicts its a simple
163
164 cvs commit
165
166 in the tree to commit your changes.
167 You should now do a
168
169 cvs tag dev-developername-feature-merge-with-main
170
171 to tag your branch at the time you merged. That way you can still work
172 on your branch and later merge it again, with only the changes you
173 added after the first merge. For that you modify the command above to
174 read as
175
176 cvs update -j dev-developername-feature-merge-with-main -j dev-developername-feature
177
178 and cvs only considers the newly added code after the first merge. If
179 you dont tag the branch cvs considers all changes, including the
180 already merged ones - that gives a lot of conflicts to resolve.
181
182
183 1.3 Muddleftpd Releases
184
185 A new version of Muddleftpd is released after it is finished. There is
186 no general timeframe like "every 2 month".
187
188 Release states:
189
190 Development
191 Development of Muddleftpd is ongoing. The work is done in MAIN
192 (see above) and in developer-created branches. You can add as
193 many new features as you want (see notes for MAIN above).
194
195 Frozen
196 From time to time Joerg will create a new Branch in the CVS
197 repository called release_X_Y_Z. X_Y_Z is replaced with the
198 version number of the upcoming release with the following
199 schema:
200 X - "Big" Major. If changed then new features in Muddleftpd
201 may break existing setups.
202 Y - Major. Changed for new features. Doesnt break old setups.
203 Z - Minor. Indicates bugfix releases and enhancments to
204 existing features. No addition of new things.
205 Sometimes there maybe a fourth part of the version number. That
206 is done for security or important releases of an existing
207 release. See 1.4
208 NO new features or enhancements are added to such a branch!
209
210 Released.
211 After creation of the release_X_Y_Z branch the code in there is
212 heavily tested and reviewed by the developers, commiting their
213 changes to that branch, so we get it as bugfree as
214 possible. Again: NO new features/enhancments are added, only
215 bugs fixed. If we get to the conclusion that we have done every
216 possible thing to ensure this, a new Release gets out and the
217 work on this branch is stopped. Get back to MAIN and your own
218 branches now and add new cool things guys :)
219
220
221 1.4 Security Updates, Important Bugfixes
222
223 It may happen that a released version of Muddleftpd has a important or
224 a security bug. Thats bad, but we are all humans, it can happen.
225 For our last official release we will follow the following procedure:
226
227 We will fix that error in the release_* branch of the last release. We
228 will NOT add any features or anything else to that tree, just fix that
229 bug and get a new stable release out. That will be numbered the same as
230 our last release with an added .X to the version number that indicates
231 that its changed. eg. a Bugfix to 1.2.9 will be 1.2.9.1, a (maybe)
232 second bugfix then 1.2.9.2 and so on.
233
234 That way we dont have to push out a new release if we dont think it is
235 finished yet (hey, we aim to produce a secure ftp daemon, that needs
236 time) but still can react quickly on such bugs.
237
238
239 1.5 ChangeLog Entries and CVS commit messages (log messages)
240
241 First please take a look at the following URL. The text there is really
242 good, you should follow it as close as possible:
243 http://www.red-bean.com/cvs2cl/changelogs.html
244
245 We require that you follow these guidelines while creating your
246 ChangeLog entry. Reasons are listed there too, mainly to have a clear
247 log of changes that are done to the source.
248
249 Talking about messages for cvs commit:
250 You can just re-use the logmessage from the ChangeLog for the commit
251 message (Emacs CVS Mode does it for you if you use that), thats fine.
252 But if you write them by Hand it is enough if you write a clear
253 sentence (or many of them) describing your changes to the file(s) you
254 commit. For details everyone could look into the ChangeLog. But NEVER
255 commit with an empty Message or just a "changed". That way everyone can
256 follow the changes you made with the cvs log output and can look into
257 the ChangeLog file for a detailed description of the changes.
258
259
260
261 1.6 Code Submission if you are not a developer of Muddleftpd
262
263 When you fix a bug or add a feature, you must submit a unified patch
264 (see below for instructions for creating the patch) to the Patch Manager
265 on Savannah, and also announce it on the mailing list (do not send the
266 patch to the list, just send a short announcement). You must NOT submit
267 the entire changed file, nor just the changed lines of code. If you
268 submit something other than a patch created using the instructions
269 below, you will be asked politely to resubmit your changes as a patch.
270 Your code will not be merged until you do.
271
272 Note: If your patch is around twice the size of the file you're
273 patching, something went wrong. DO NOT submit that patch. If you edited
274 the file on a non-unix system, and transferred it to a unix system to
275 run diff on it, you need to make sure the end-of-line characters are the
276 unix kind. Ask on the mailing list if you have this problem.
277
278 Example:
279 To create a unified patch suitable for submission, have both your modified
280 source tree and the original source tree avaliable. Prepare both trees for
281 comparison by running the following (on both trees):
282
283 bash$ ./configure
284 bash$ make maintainer-clean
285
286 Now compare the two trees using the following command:
287
288 bash$ diff -r -u3 [path to original tree] [path to modified tree] > patchfile
289
290 Patchfile will now contain your patch and you can submit it. Be sure that
291 you don't mix the original and modified tree paths up, otherwise your patch
292 will end up backwards.
293
294 Note: if you need to use your tree again after creating the patch, simply run
295 ./autogen.sh in the source tree. This will automaticly regenerate all the
296 configure scripts.
297
298
299 1.7 How to become a developer
300
301 Well, thats not that hard. Of course we require a little knowledge, so
302 you have to prove you can do the work you say you want to do.
303
304 If you want to work on muddleftpd's source you need to do that before
305 you get access. Just write some enhancement/new feature to muddleftpd
306 (look at the task list for ideas what can be done). You do that with
307 the latest copy of the CVS Source. Then use diff -u or cvs diff -u to
308 create a patch and submit that at the Savannah project.
309
310 If you want to work on the documentation or website part it is mainly
311 the same:
312 Show us that you are able to do this and you can get your access.

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26