Contributors to GNU Alive are welcome, but please follow the below
guidelines. More specifically, the section on patches.


Working with GNU Alive
======================

The alive daemon is divided into logical blocks:

etc/
lib/
  conf/
  html/
src/

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


The alive 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 counter argument.  However,
let there be no doubt, the GCS does apply to GNU Alive.  Also, take a
look at the Gtk+ header files (or recent kernel documentation efforts
in the Linux kernel) to get acquainted with how to write nice header
files that are almost self documenting.  The intention is to generate
all developer documentation from the source using GDOC and LaTeX.

Uses spaces instead of tabs and set Emacs to use GNU indentation style,
"C-c ." is the short key.  See the bottom of each source file for how
to let Emacs know how to indent a certain file.

GNU Alive is prepared for gtk-doc function header comment parsing. 
Please follow that style of coding.  See examples and documentation
on http://www.josefsson.org/gdoc/, for more information.

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-alive-file-brief-description.diff

Otherwise the following always applies:

# ls 
alive-orig alive

# diff -ruN alive-orig alive >patch-alive-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-alive-brief-description.diff


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

First we try to make sure the HEAD of alive 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_4 is actually alive-1.3.4 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.4-1

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

Fifth, from that directory a tar.gz source distribution is built:
cd alive-major.minor.fix-cvs/
./configure                    <--- Just to get a Makefile
make dist
mv alive-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 alive-major.minor.fix.tar.gz
cd alive-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/alive/.
All relevant files is then uploaded using anonymous FTP to the
above location.

