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