Muddleftpd Developer Guidelines

This is: $Revision: 1.3 $.

[Note before: That text is assembled from different other guidelines I
read and some talks I had with other people.]

Contents

1.0 Copyright issues
1.1 Preface
1.2 CVS Branches
1.3 Muddleftpd Releases
1.4 Security Updates, Important Bugfixes
1.5 ChangeLog Entries and CVS commit messages (log messages)
1.6 Code Submission if you are not a developer of Muddleftpd
1.7 How to become a developer


1.0 Copyright issues
Muddleftpd is developed under the GNU GPL license. Every code you
write/add to Muddleftpd has to be under the same license.
Every source file has to include the following lines at the top of the
file (you may change the comment style if needed):

/* FILENAME SHORT DESCRIPTION OF THE FILE

   Copyright (C) 2002 Muddleftpd Team, http://www.nongnu.org/muddleftpd/

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2, or (at your option)
   any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/



1.1 Preface

So that we can all work together in the most productive way, all
developers working on the code in CVS should follow the following
guidelines.

- You break it, you fix it. If you break something that was working
  before you checked in your code, it's your responsebility to get
  it working again. If you ask the other developers real nicely,
  maybe they'll help you, but it is your responsability.

- Try to keep all your changes limited to the specific area you are
  working on.

- Peoples interests change. Workloads change. So if you have code
  for a task you are working on that is an improvement on what is
  in CVS already, feel good about checking it in. If it doesnt break
  anything, and adds/fixes something, it's a good thing to add to
  the repository.

  If you're working on something complex, and you want something
  committed as an intermediate step, then it might be okay to commit
  what you have. But try not to commit anything that is completely
  broken. At minimum, check in something that is partially working,
  with clear comments about "this isnt working yet, but this is what
  I'm in the process of doing to get there".

- Write good cvs commit messages. Not just "modified" or blank lines.
  It will be used for the ChangeLog, so it should really show what you
  have done. A URL with good hints for ChangeLog entries is
  http://www.red-bean.com/cvs2cl/changelogs.html
  If you follow that as close as possible for your commit message
  everything is fine.


1.2 CVS Branches

The Muddleftpd CVS repository has one primary tree, called MAIN. They
can be 0 to many branches used for quality control and developing new
features.
Note: All branch identifiers and tag names starting with release_ are
reserved and only used to indicate different release versions.

   MAIN
   This tree is under full control of Beau Kuiper. If you want to
   change things here you have to get his OK first. That is to ensure
   the quality and security of muddleftpd because all code added here
   has to be fully reviewed. This tree will be branched to create new
   releases and everyone that commits here (after the OK) has to make
   sure HE DOESNT BREAK IT.

   release_*
   These branches are under control of Joerg Jaspert. He is the only
   one who makes new releases. * is replaced with some information, see
   1.3 below.
   Such a branch is the place to fix bugs in a released version. See
   below for more about that.

   dev_NICK_feature
   Every developer is allowed to create a branch within the
   repository. Just replace NICK with the nick you have on Savannah and
   feature with the feature you want to develop in that branch. That
   way everyone knows whats going on with a particular branch.
   He is then fully responsible for that branch, so if you want to work
   on anothers developers branch talk to him first.
   Developers can use that to work on new features/enhancements without
   breaking the MAIN tree of muddleftpd and without the rules that are
   for that tree.
   Example: If you want to work on IPV6 support you create a branch
   called something like 'ipv6' and do your work in it. Every then and
   now you look at MAIN if there are interesting changes and merge them
   into your branch if you like them. After a while you are finished
   and at the point where you can say "Yes, its stable and good enough
   for MAIN". Then you "freeze" this tree, eg. stop working on it and
   telling all other that its frozen and coordinate with Beau to get it
   merged into MAIN. Then you only commit things into that branch that
   are needed to get it accepted into MAIN, and after all things are
   sorted out you and Beau merge it into MAIN. Voila, a new feature is
   there without breaking of our MAIN line. :)

If you ever create a branch and find out later that you dont need it,
you can remove that branch from the repository. The project admins are
allowed to do that for dead branches that arent used for longer then 2
months to keep the repository clean.
But please never remove a branch that has development work in it, even
if it is not used at the moment or looks like it never will again. It
may contain important source changes/ ways to solve a problem we can
use at a later time.



1.3 Muddleftpd Releases

A new version of Muddleftpd is released after it is finished. There is
no general timeframe like "every 2 month".

Release states:

	Development
	Development of Muddleftpd is ongoing. The work is done in MAIN
	(see above) and in developer-created branches. You can add as
	many new features as you want (see notes for MAIN above).

	Frozen
	From time to time Joerg will create a new Branch in the CVS
	repository called release_X_Y_Z. X_Y_Z is replaced with the
	version number of the upcoming release with the following
	schema:
	X - "Big" Major. If changed then new features in Muddleftpd
	  	may break existing setups.
	Y - Major. Changed for new features. Doesnt break old setups.
	Z - Minor. Indicates bugfix releases and enhancments to
	    existing features. No addition of new things.
	Sometimes there maybe a fourth part of the version number. That
	is done for security or important releases of an existing
	release. See 1.4
	NO new features or enhancements are added to such a branch!

	Released.
	After creation of the release_X_Y_Z branch the code in there is
	heavily tested and reviewed by the developers, commiting their
	changes to that branch, so we get it as bugfree as
	possible. Again: NO new features/enhancments are added, only
	bugs fixed. If we get to the conclusion that we have done every
	possible thing to ensure this, a new Release gets out and the
	work on this branch is stopped. Get back to MAIN and your own
	branches now and add new cool things guys :)


1.4 Security Updates, Important Bugfixes

It may happen that a released version of Muddleftpd has a important or
a security bug. Thats bad, but we are all humans, it can happen.
For our last official release we will follow the following procedure:

We will fix that error in the release_* branch of the last release. We
will NOT add any features or anything else to that tree, just fix that
bug and get a new stable release out. That will be numbered the same as
our last release with an added .X to the version number that indicates
that its changed. eg. a Bugfix to 1.2.9 will be 1.2.9.1, a (maybe)
second bugfix then 1.2.9.2 and so on.

That way we dont have to push out a new release if we dont think it is
finished yet (hey, we aim to produce a secure ftp daemon, that needs
time) but still can react quickly on such bugs.


1.5 ChangeLog Entries and CVS commit messages (log messages)

First please take a look at the following URL. The text there is really
good, you should follow it as close as possible:
http://www.red-bean.com/cvs2cl/changelogs.html

We require that you follow these guidelines while creating your
ChangeLog entry. Reasons are listed there too, mainly to have a clear
log of changes that are done to the source.

Talking about messages for cvs commit:
You can just re-use the logmessage from the ChangeLog for the commit
message (Emacs CVS Mode does it for you if you use that), thats fine.
But if you write them by Hand it is enough if you write a clear
sentence (or many of them) describing your changes to the file(s) you
commit. For details everyone could look into the ChangeLog. But NEVER
commit with an empty Message or just a "changed". That way everyone can
follow the changes you made with the cvs log output and can look into
the ChangeLog file for a detailed description of the changes.



1.6 Code Submission if you are not a developer of Muddleftpd

When you fix a bug or add a feature, you must submit a unified patch
(see below for instructions for creating the patch) to the Patch Manager
on Savannah, and also announce it on the mailing list (do not send the
patch to the list, just send a short announcement). You must NOT submit
the entire changed file, nor just the changed lines of code. If you
submit something other than a patch created using the instructions
below, you will be asked politely to resubmit your changes as a patch.
Your code will not be merged until you do.

Note: If your patch is around twice the size of the file you're
patching, something went wrong. DO NOT submit that patch. If you edited
the file on a non-unix system, and transferred it to a unix system to
run diff on it, you need to make sure the end-of-line characters are the
unix kind. Ask on the mailing list if you have this problem.

Example:
To create a unified patch suitable for submission, have both your modified 
source tree and the original source tree avaliable. Prepare both trees for 
comparison by running the following (on both trees):

bash$ ./configure
bash$ make maintainer-clean

Now compare the two trees using the following command:

bash$ diff -r -u3 [path to original tree] [path to modified tree] > patchfile

Patchfile will now contain your patch and you can submit it. Be sure that 
you don't mix the original and modified tree paths up, otherwise your patch 
will end up backwards.

Note: if you need to use your tree again after creating the patch, simply run 
./autogen.sh in the source tree. This will automaticly regenerate all the 
configure scripts.


1.7 How to become a developer

Well, thats not that hard. Of course we require a little knowledge, so
you have to prove you can do the work you say you want to do.

If you want to work on muddleftpd's source you need to do that before
you get access. Just write some enhancement/new feature to muddleftpd
(look at the task list for ideas what can be done). You do that with
the latest copy of the CVS Source. Then use diff -u or cvs diff -u to
create a patch and submit that at the Savannah project.

If you want to work on the documentation or website  part it is mainly
the same: 
Show us that you are able to do this and you can get your access.