Contributors to qadsl are welcome, but please follow the below
guide lines. Specifically the section on patches.


Working with qadsl
==================

The qadsl daemon is divided into logical blocks:

etc/
lib/
  conf/
  html/
src/

http://www.gnu.org/prep/maintain_toc.html


The qadsl coding style
======================

Make yourself familiar with the the GNU Coding Standards (GCS). It is
shipped with most GNU/Linux systems as the standards.info file), then 
read linux/Documentation/CodingStyle for a good laugh. Let there be no
doubt, the GCS do apply to qadsl. Also, take a look at the Gtk+ header
files to get acquainted with how to write nice header files that are
almost self documenting. 

Uses spaces instead of tabs and set Emacs to use GNU indentation style,
"C-c ." is the short key.

TODO: add emacs style file headers -*-C-*- plus magic of setting
      up the rest correctly (spaces for tabs and GNU style).

qadsl is prepared for gtk-doc function header comment parsing. Please
follow that style of coding.

Example:

   /**
    * function_name - Short description
    * @variable_1: Description.
    * @variable_2: Description.
    * @variable_3: Description.
    * @variable_4: Description.
    *
    * Empty line, then function description with references to
    * input variables like @variable_1 or other functions(), 
    * %CONSTANTS and more. See the gtk-doc specification written
    * originally by Miguel de Icaza. 
    *
    * New subsections are started like this:
    *
    * Subsection: yada yada
    *
    * Finish off with the output/generated data.
    *
    * Returns: -1 for all errors.
    *           0 when OK.
    */

For all other multi-line comments use

   /* text
    * is written
    * like
    * this.
    */


TODO vs. NEWS items
===================

The top directory contains the TODO and NEWS files. Items listed in the 
TODO are free to be fixed by anyone by submission of a patch (see below).
When a patch has been deemed fit enough for inclusion the TODO item is
transformed to a NEWS item for the next release.


Submitting patches
==================

Patches are preferably submitted against the latest CVS head revision of
the file(s) in question. Also, to be included a proper GCS formatted
ChangeLog entry must be subitted -- in proper readable format, not diffed.

# cvs diff -u -r HEAD filename > patch-qadsl-file-brief-description.diff

Otherwise the following always applies:

# ls 
qadsl-orig qadsl

# diff -ruN qadsl-orig qadsl >patch-qadsl-brief-description.diff

If the .diff is a bit on the large side it can be gzipped,
or bzip2:ed. But for small diffs that is not recommended.

# gzip -9 patch-qadsl-brief-description.diff


Doing releases
==============

First we try to make sure the HEAD of qadsl builds, installs and works 
at least within some basic boundaries of what one could expect.

Second we do some sort of freeze where we cancel CVS commits, only
the release engineer is allowed to commit changes. Only critical 
patches are let in. This freeze phase is preferably done on its
own release branch, patches made on this branch should of course
also be committed on HEAD.

Third, the branch (might still be HEAD) is tagged using the following
notation:

	RELEASE-MAJOR_MINOR_FIX
                  |     |    |
                  |     |    +------ Fix/Patch release number
                  |     +----------- Minor number, minor feature additions.
                  +----------------- Major stuff, big code rewrites etc.
Example:
       RELEASE-1_3_1 is actually qadsl-1.3.1 where dots are replaced with
       underscores. It's just that simple! :-)

Also, the files configure.in and debian/changelog are updated to reflect the
new release number. To update debian/changelog use the following command:
cd debian
debchange -v 1.3.1-1

Fourth, when tagged a new tree is checked out from CVS using the following:
cvs co -r RELEASE-MAJOR_MINOR_FIX -d qadsl-major.minor.fix-cvs qadsl

Fifth, from that directory a tar.gz source distribution is built:
cd qadsl-major.minor.fix-cvs/
./configure                    <--- Just to get a Makefile
make dist
mv qadsl-major.minor.fix.tar.gz ../
cd ..

Sixth, the built source distribution is then the basis for the deb
(and rpm) package(s). Like this:
tar xvfz qadsl-major.minor.fix.tar.gz
cd qadsl-major.minor.fix/
dpkg-buildpackage -tc -b

Signing of the debs can, at this point, only be done by the deb
package maintainer.

Seventh, the .tar.gz and .deb files are signed with gpg -b before
being uploaded to ftp://savannah.gnu.org/incoming/savannah/qadsl/.
All relevant files is then uploaded using anonymous FTP to the
above location.

