Unlink lockfiles for old feeds

[innduct.git] / doc / pod / hacking.pod

=head1 Hacking INN

This file is for people who are interested in making modifications to INN.
Normal users can safely skip reading it.  It is intended primarily as a
guide, resource, and accumulation of tips for maintainers and
contributors, and secondarily as documentation of some of INN's internals.

This is $Revision: 7518 $ dated $Date: 2006-04-14 19:52:06 -0700 (Fri, 14 Apr 2006) $.

First of all, if you plan on working on INN source, please start from the
current development tree.  There may be significant changes from the
previous full release, so starting from development sources will make it
considerably easier to integrate your work.  You can get nightly snapshots
of the current development source from ftp.isc.org in /isc/inn/snapshots
(the snapshots named inn-CURRENT-*.tar.gz), or you can get the current CVS
tree by using CVSup (see L<"Using CVSup">).

=head1 Configuring and Portability

All INN code should be written expecting ANSI C and POSIX.  There is no
need to attempt to support pre-ANSI compilers, and ANSI-only features such
as <stdarg.h>, string concatenation, #elif, and token pasting may be used
freely.  So far as possible, INN is written to attempt to be portable to
any system new enough that someone is likely to want to run a news server
on it, but whenever possible this portability should be provided by
checking for standard behavior in configure and supplying replacements for
standard functions that are missing.

When there is a conflict between ANSI C and C99, INN code should be
written expecting C99 and autoconf used to patch up the differences.

Try to avoid using #ifdef and the like in the middle of code as much as
possible.  Instead, try to isolate the necessary portability bits and
include them in libinn or at least in conditional macros separate from the
code.  Trying to read code littered with conditional compilation
directives is much more difficult.

The shell script F<configure> at the top level of the source tree is
generated by autoconf from F<configure.in>, and F<include/config.h.in> is
generated by autoheader from F<configure.in> and F<include/acconfig.h>.
At configure time, configure generates F<include/config.h> and several
other files based on options it was given and what it discovers about the
target system.

All modifications to configure should instead be made to F<configure.in>.
Similarly, modifications to F<include/config.h.in> should instead be made
to F<include/acconfig.h>.  The autoconf manual (available using info
autoconf if you have autoconf and the GNU info utilities installed on your
system) is a valuable reference when making any modifications.

To regenerate configure, just run C<autoconf>.  To regenerate
F<include/config.h.in>, run:

    autoheader -l include

to tell it where to find acconfig.h.  Please don't include patches to
either F<configure> or F<include/config.h.in> when sending patches to INN;
instead, note in your patch that those files must be regenerated.

The generated files are checked into the CVS repository so that people
working on INN don't have to have autoconf on their system, and to make
packaging easier.

At the time of this writing, autoconf 2.13 is required.

The supporting files for autoconf are in the F<support> subdirectory,
including the files F<config.guess> and F<config.sub> to determine the
system name and and F<ltmain.sh> for libtool support.  The latter file
comes from the libtool distribution; the canonical version of the former
two are available from ftp.gnu.org in /gnu/config.  In addition,
F<m4/libtool.m4> is just a copy of F<libtool.m4> from the libtool
distribution.  (Using libtool without using automake requires a few odd
hacks.)  These files used to be on a separate vendor branch so that we
could make local modifications, but local modifications have not been
necessary for some time.  Now, new versions can just be checked in like
any other file modifications.

INN should not compile with libtool by default, only when requested, since
otherwise normal compilations are quite slow.  (Using libtool is not
without some cost.)  Basic compilation with libtool works fine as of this
writing, with both static and shared compiles, but the dependencies aren't
quite right for make -j using libtool.

=head1 Documentation

INN's documentation is currently somewhat in a state of flux.  The vast
majority is still in the form of man pages written directly in nroff.
Some parts of the documentation have been rewritten in POD; that
documentation can be found in F<doc/pod>.  The canonical source for
F<README>, F<INSTALL>, F<NEWS>, F<doc/hook-perl>, F<doc/hook-python>, and
this file are also in POD.

If you're modifying some part of INN's documentation and see that it has a
POD version in F<doc/pod>, it's preferred if you can make the
modifications to the POD source and then regenerate the derived files.
For a quick introduction to POD, see the perlpod(1) man page on your
system (it should be installed if you have Perl installed).

When writing new documentation, write in whatever format you care to; if
necessary, we can always convert it to POD or whatever else we want to
use.  Having the documentation exist in I<some> form is more important
than what language you write it in.  If you really don't have any
particular preference, there's a slight preference currently for POD.

If you use POD or regenerate POD documentation, please install something
close to the latest versions of the POD processing utilities to avoid
changes to the documentation depending on who generated it last.  You can
find the latest version on CPAN (ftp.perl.org or another mirror) in
F<modules/by-module/Pod>.  You'll need PodParser (for versions of Perl
before 5.6.1; 5.6.1 and later come with a recent enough version) and the
latest version of podlators.  For versions of Perl earlier than 5.005,
you'll also need File::Spec in F<modules/by-module/File>.

podlators 1.25 or later will build INN's documentation without significant
changes from the versions that are checked into the repository.

There are Makefile rules in F<doc/pod/Makefile> to build all of the
documentation whose master form is POD; if you add additional
documentation, please add a rule there as well.  Documentation should be
generated by cd'ing to F<doc/pod> and typing C<make file> where C<file> is
the relative path to the documentation file.  This will get all of the
various flags right for pod2text or pod2man.

=head1 Error Handling

INN has a set of generic error handling routines that should be used as
much as possible so that the same syntax can be used for reporting errors
everywhere in INN.  The four basic functions are warn, syswarn, die, and
sysdie; warn prints or logs a warning, and die does the same and then
exits the current program.  The sys* versions add a colon, a space, and
the value of strerror(errno) to the end of the message, and should be used
to report failing system calls.

All of the actual error reporting is done via error handlers, and a
program can register its own handlers in addition to or instead of the
default one.  The default error handler (error_log_stderr) prints to
stderr, prepending the value of error_program_name if it's set to
something other than NULL.  Three other error handlers are available,
error_log_syslog_crit, error_log_syslog_err, and error_log_syslog_warning,
which log the message to syslog at LOG_CRIT, LOG_ERR, or LOG_WARNING
priority, respectively.

There is a different set of error handlers for warn/syswarn and
die/sysdie.  To set them, make calls like:

    warn_set_handlers(2, error_log_stderr, error_log_syslog_warning);
    die_set_handlers(2, error_log_stderr, error_log_syslog_err);

The first argument is the number of handlers, and the remaining arguments
are pointers to functions taking an int (the length of the formatted
message), a const char * (the format), a va_list (the arguments), and an
int that's 0 if warn or die was called and equal to the value of errno if
syswarn or sysdie was called.  The length of the formatted message is
obtained by calling vsnprintf with the provided format and arguments, and
therefore is reliable to use as the size of a buffer to malloc to hold the
result of formatting the message provided that vsnprintf is used to format
it (warning: the system vsprintf may produce more output under some
circumstances, so always use vsnprintf).

The error handler can do anything it wishes; each error handler is called
in the sequence given.  Error handlers shouldn't call warn or die unless
great caution is taken to prevent infinite recursion.  Also be aware that
sysdie is called if malloc fails in xmalloc, so if the error handler needs
to allocate memory, it must not use xmalloc or a related function to do
so and it shouldn't call die to report failure.  The default syslog
handlers report memory allocation failure to stderr and exit.

Finally, die and sysdie support an additional handler that's called
immediate before exiting, takes no arguments, and returns an int which is
used as the argument for exit.  It can do any necessary global cleanup,
call abort instead to generate a core dump or the like.

The advantage of using this system everywhere in INN is that library code
can use warn and die to report errors and each calling program can set up
the error handlers as appropriate to make sure the errors go to the right
place.  The default handler is fine for interactive programs; for programs
that run from interactive scripts, adding something like:

    error_program_name = "program";

to the beginning of main (where program is the name of the program) will
make it easier to figure out which program the script calls is failing.
For programs that may also be called non-interactively, like inndstart,
one may want to set up handlers like:

    warn_set_handlers(2, error_log_stderr, error_log_syslog_warning);
    die_set_handlers(2, error_log_stderr, error_log_syslog_err);

Finally, for daemons and other non-interactive programs, one may want to
do:

    warn_set_handlers(1, error_log_syslog_warning);
    die_set_handlers(1, error_log_syslog_err);

to report errors only via syslog.  (Note that if you use syslog error
handlers, the program should call openlog first thing to make sure they
are logged with the right facility.)

For historical reasons, error messages that are fatal to the news
subsystem are logged at the LOG_CRIT priority, and therefore die in innd
should use error_log_syslog_crit.

=head1 Test Suite

The test suite for INN is located in the tests directory and is just
getting started.  The test suite consists of a set of programs listed in
F<tests/TESTS> and the scaffolding in the F<runtests> program.

Adding new tests is very straightforward and very flexible.  Just write a
program that tests some part of INN, put it in a directory under tests
named after the part of INN it's testing (all the tests so far are in lib
because they're testing libinn routines), and have it output first a line
containing the count of test cases in that file, and then for each test a
line saying "ok n" or "not ok n" where n is the test case number.  (If a
test is skipped for some reason, such as a test of an optional feature
that wasn't compiled into INN, the test program should output
S<"ok n # skip">.)  Add any rules necessary to build the test to
tests/Makefile (note that for simplicity it doesn't recurse into
subdirectories) and make sure it creates an executable ending in F<.t>.
Then add the name of the test to tests/TESTS, without the .t ending.

One naming convention:  to distinguish more easily between e.g.
lib/error.c (the implementation) and tests/lib/error-t.c (the test suite),
we add -t to the end of the test file names.  So tests/lib/error-t.c is
the source that compiles into an executable tests/lib/error.t which is run
by putting a line in tests/TESTS of just "lib/error".

Note that tests don't have to be written in C; in fact, lib/xmalloc.t is
just a shell script (that calls a supporting C program).  Tests can be
written in shell or Perl (but other languages should be avoided because
someone who wants to run the test suite may not have it) and just have to
follow the above output conventions.

Additions to the test suite, no matter how simple, are very welcome.

=head1 Makefiles

All INN makefiles include Makefile.global at the top level, and only that
makefile is a configure substitution target.  This has the disadvantage
that configure's normal support for building in a tree outside of the
source tree doesn't work, but it has the significant advantage of making
configure run much faster and allowing one to run make in any subdirectory
and pick up all the definitions and settings from the top level
configuration.

All INN makefiles should also set $(top) to be the path to the top of the
build directory (usually relative).  This path is used to find various
programs like fixscript and libtool so that the same macros (set in
Makefile.global) can be used all over INN.

The format of INN's makefiles is mostly standardized; the best examples of
the format are probably F<frontends/Makefile> and F<backends/Makefile>, at
least for directories with lots of separate programs.  The ALL variable
holds all the files that should be generated, EXTRA those additional files
that were generated by configure, and SOURCES the C source files for
generating tag information.

There are a set of standard installation commands defined in make
variables by Makefile.global, and these should be used for all file
installations.  See the comment blocks in Makefile.global.in for
information on what commands are available and when they should be used.
There are also variables set for each of the installation directories that
INN uses, for use in building the list of installed paths to files.

Each subdirectory makefile should have the targets all (the default),
clean, clobber, install, tags, and profiled.  The tags target generates vi
tags files, and the profiled target generates a profiling version of the
programs (although this hasn't been tested much recently).  These rules
should be present and empty in those directories where they don't apply.

Be sure to test compiling with both static and dynamic libraries and make
sure that all the libtool support works correctly.  All linking steps, and
the compile steps for all library source, should be done through
$(LIBTOOL) (which will be set to empty in Makefile.global if libtool
support isn't desired).

=head1 Scripts

INN comes with and installs a large number of different scripts, both
Bourne shell and Perl, and also comes with support for Tcl scripts
(although it doesn't come with any).  Shell variables containing both
configure-time information and configuration information from inn.conf are
set by the innshellvars support libraries, so the only system-specific
configuration that should have to be done is fixing the right path to the
interpretor and adding a line to load the appropriate innshellvars.

F<support/fixscript>, built by configure, does this.  It takes a .in file
and generates the final script (removing the .in) by fixing the path to
the interpretor on the first line and replacing the second line, whatever
it is, with code to load the innshellvars appropriate for that
interpretor.  (If invoked with -i, it just fixes the interpretor path.)

Scripts should use innshellvars (via fixscript) to get the right path and
the right variables whenever possible, rather than having configure
substitute values in them.  Any values needed at run-time should instead
be available from all of the different innshellvars.

See the existing scripts for examples of how this is done.

=head1 Include Files

Include files relevant to all of INN, or relevant to the two libraries
built as part of INN (the utility libinn library and the libstorage
library that contains all storage and overview functions) are found in the
include directory; other include files relevant only to a portion of INN
are found in the relevant directory.

Practically all INN source files will start with:

    #include "config.h"
    #include "clibrary.h"

The first picks up all defines generated by autoconf and is necessary for
types that may not be present on all systems (uid_t, pid_t, size_t,
int32_t, and the like).  It therefore should be included before any other
headers that use those types, as well as to get general configuration
information.

The second is portably equivalent to:

    #include <sys/types.h>
    #include <stdarg.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <stddef.h>
    #include <stdint.h>
    #include <string.h>
    #include <unistd.h>

except that it doesn't include headers that are missing on a given system,
replaces functions not found on the system with the INN equivalents,
provides macros that INN assumes are available but which weren't found,
and defines some additional portability things.  Even if this is more
headers than the source file actually needs, it's generally better to just
include F<clibrary.h> rather than trying to duplicate the autoconf-driven
hackery that it does to do things portably.  The primary exception is for
source files in lib that only define a single function and are used for
portability; those may want to include only F<config.h> so that they can
be easily used in other projects that use autoconf.  F<config.h> is a
fairly standard header name for this purpose.

F<clibrary.h> does also include F<config.h>, but it's somewhat poor form
to rely on this; it's better to explicitly list the header dependencies
for the benefit of someone else reading the code.

There are portable wrappers around several header files that have known
portability traps or that need some fixing up on some platforms.  Look in
include/portable and familiarize yourself with them and use them where
appropriate.

Another frequently included header file is F<libinn.h>, which among other
things defines xmalloc(), xrealloc(), xstrdup(), and xcalloc(), which are
checked versions of the standard memory allocation routines that terminate
the program if the memory allocation fails.  These should generally always
be used instead of the regular C versions.  F<libinn.h> also provides
various other utility functions that are frequently used.

F<paths.h> includes a wide variety of paths determined at configure time,
both default paths to various parts of INN and paths to programs.  Don't
just use the default paths, though, if they're also configurable in
F<inn.conf>; instead, call ReadInnConf() and use the global innconf
structure.

Other files in include are interfaces to particular bits of INN library
functionality or are used for other purposes; see the comments in each
file.

Eventually, the header files will be separated into installed header files
and uninstalled header files; the latter are those headers that are used
only for compiling INN and aren't useful for users of INN's libraries
(such as clibrary.h).  All of the installed headers will live in
include/inn and be installed in a subdirectory named inn in the configured
include directory.  This conversion is still in progress.

When writing header files, remember that C reserves all identifiers
beginning with two underscores and all identifiers beginning with an
underscore and a capital letter for the use of the implementation; don't
use any identifiers with names like that.  Additionally, any identifier
beginning with an underscore and a lower-case letter is reserved in file
scope, which means that such identifiers can only be used by INN for the
name of structure members or function arguments in function prototypes.

Try to pay attention to the impact of a header file on the program
namespace, particularly for installed header files in include/inn.  All
symbols defined by a header file should ideally begin with INN_, inn_, or
some other unique prefix indicating the subsystem that symbol is part of,
to avoid accidental conflicts with symbols defined by the program that
uses that header file.

=head1 Coding Style

INN has quite a variety of coding styles intermixed.  As with all
programs, it's preferrable when making minor modifications to keep the
coding style of the code you're modifying.  In INN, that will vary by
file.  (Over time we're trying to standardize on one coding style, so
changing the region you worked on to fit the general coding style is also
acceptable).

If you're writing a substantial new piece of code, the prevailing
"standard" INN coding style appears to be something like the following:

=over 3

=item *

Write in regular ANSI C whenever possible.  Use the normal ANSI and POSIX
constructs and use autoconf or portability wrappers to fix things up
beforehand so that the code itself can read like regular ANSI or POSIX
code.  Code should be written so that it works as expected on a modern
platform and is fixed up with portability tricks for older platforms, not
the other way around.  You may assume an ANSI C compiler.

Try to use const wherever appropriate.  Don't use register; modern
compilers will do as good of a job as you will in choosing what to put
into a register.  Don't bother with restrict (at least yet).

=item *

Use string handling functions that take counts for the size of the buffer
whenever possible.  This means using snprintf in preference to sprintf and
using strlcpy and strlcat in preference to strcpy and strcat.  Also, use
strlcpy and strlcat instead of strncpy and strncat unless the behavior of
the latter is specifically required, as it is much easier to audit uses of
the former than the latter.  (strlcpy is like strncpy except that it
always nul-terminates and doesn't fill the rest of the buffer with nuls,
making it more efficient.  strlcat is like strncat except that it always
nul-terminates and it takes the total size of the buffer as its third
argument rather than just the amount of space left.)  All of these
functions are guaranteed to be available; there are replacements in lib
for systems that don't have them.

=item *

Avoid #ifdef and friends whenever possible.  Particularly avoid using them
in the middle of code blocks.  Try to hide all portability preprocessor
magic in header files or in portability code in lib.  When something just
has to be done two completely different ways depending on the platform or
compile options or the like, try to abstract that functionality out into a
generic function and provide two separate implementations using #ifdef;
then the main code can just call that function.

If you do have to use preprocessor defines, note that if you always define
them to either 0 or 1 (never use #define without a second argument), you
can use the preprocessor define in a regular if statement rather than
using #if or #ifdef.  Make use of this instead of #ifdef when possible,
since that way the compiler will still syntax-check the other branch for
you and it makes it far easier to convert the code to use a run-time check
if necessary.  (Unfortunately, this trick can't be used if one branch may
call functions unavailable on a particular platform.)

=item *

Avoid uses of fixed-width buffers except in performance-critical code, as
it's harder to be sure that such code is correct and it tends to be less
flexible later on.  If you need a reusable, resizable memory buffer, one
is provided in lib/buffer.c.

=item *

Avoid uses of static variables whenever possible, particularly in
libraries, because it interferes with making the code re-entrant down the
road and makes it harder to follow what's going on.  Similarly, avoid
using global variables whenever possible, and if they are required, try to
wrap them into structures that could later be changed into arguments to
the affected functions.

=item *

Roughly BSD style but with four-space indents.  This means no space before
the parens around function arguments, open brace on the same line as
if/while/for, and close and open brace on the same line as else).

=item *

Introductory comments for functions or files are generally written as:

    /*
    **  Introductory comment.
    */

Other multiline comments in the source are generally written as:

    /* This is a
       multiline comment. */

Comments before functions saying what they do are nice to have.  In
general, the RCS/CVS Id tag is on the first line of each source file since
it's useful to know when a file was last modified.

=item *

Checks for NULL pointers are preferrably written out explicitly; in other
words, use:

    if (p != NULL)

rather than:

    if (p)

to make it clearer what the code is assuming.

=item *

It's better to always put the body of an if statement on a separate line,
even if it's only a single line.  In other words, write:

    if (p != NULL)
        return p;

and not:

    if (p != NULL) return p;

This is in part for a practical reason:  some code coverage analysis tools
like purecov will count the second example above as a single line and
won't notice if the condition always evaluates the same way.

=item *

Plain structs make perfectly reasonable abstract data types; it's not
necessary to typedef the struct to something else.  Structs are actually
very useful for opaque data structures, since you can predeclare them and
then manipulate pointers to them without ever having to know what the
contents look like.  Please try to avoid typedefs except for function
pointers or other extremely confusing data types, or for data types where
we really gain some significant data abstraction from hiding the
underlying data type.  Also avoid using the _t suffix for any type; all
types ending in _t are reserved by POSIX.  For typedefs of function
pointer types, a suffix of _func usually works.

This style point is currently widely violated inside of INN itself; INN
originally made extensive use of typedefs.

=item *

When noting something that should be improved later, add a comment
containing "FIXME:" so that one can easily grep for such comments.

=back

INN's indentation style roughly corresponds to that produced by GNU indent
2.2.6 with the following options:

    -bad -bap -nsob -fca -lc78 -cd41 -cp1 -br -ce -cdw -cli0 -ss -npcs
    -ncs -di1 -nbc -psl -brs -i4 -ci4 -lp -ts8 -nut -ip5 -lps -l78 -bbo
    -hnl

Unfortunately, indent currently doesn't get everything right (it has
problems with spacing around struct pointer arguments in functions, wants
to put in a space between a dereference of a function pointer and the
arguments to the called function, misidentifies some macro calls as being
type declarations, and fouls up long but simple case statements).  It
would be excellent if someday we could just run all of INN's code through
indent routinely to enforce a consistant coding style, but indent isn't
quite ready for that.

For users of emacs cc-mode, use the "bsd" style but with:

    (setq c-basic-offset 4)

Finally, if possible, please don't use tabs in source files, since they
can expand differently in different environments.  In particular, please
try not to use the mix of tabs and spaces that is the default in emacs.
If you use emacs to edit INN code, you may want to put:

    ; Use only spaces when indenting or centering, no tabs.
    (setq-default indent-tabs-mode nil)

in your ~/.emacs file.

Note that this is only a rough guideline and the maintainers aren't style
nazis; we're more interested in your code contribution than in how you
write it.

=head1 Using CVSup

If you want to get updated INN source more easily or more quickly than by
downloading nightly snapshots, or if you want to see the full CVS history,
you may want to use CVSup to download the source.  CVSup is a client and
server designed for replicating CVS repositories between sites.

Unfortunately, CVSup is written in Modula-3, so getting a working binary
can be somewhat difficult.  Binaries are available in the *BSD ports
collection or (for a wide variety of different platforms) available from
<ftp://ftp.freebsd.org/pub/FreeBSD/CVSup/binaries/> and its mirrors.
Alternately, you can get a compiler from <http://m3.polymtl.ca/m3/> (this
is more actively maintained than the DEC Modula-3 compiler) and the source
from <ftp://ftp.freebsd.org/pub/FreeBSD/CVSup/>.

After you have the CVSup client, you need to have space to download the
INN repository and space for CVSup to store its data files.  You also need
to write a configuration file (a supfile) for CVSup.  The following
supfile will download the latest versions from the mainline source:

    *default host=inn-cvs.isc.org
    *default base=<data-location>
    *default prefix=<download-location>
    *default release=cvs
    *default tag=.
    *default delete use-rel-suffix
    inn

where <data-location> should be a directory where CVSup can put its data
files and <download-location> is where the downloaded source will go (it
will be put into a subdirectory named inn).  If you want to pull down the
entire CVS repository instead (warning: this is much larger than just the
latest versions of the source), delete the C<*default tag=.> line.  The
best way to download the CVS repository is to download it into a portion
of a locally-created CVS repository, so that then you can perform standard
CVS operations (like cvs log) against the downloaded repository.  Creating
your own local CVS repository is outside the scope of this document.

Note that only multiplexed mode is supported (this mode should be the
default).

For more general information on using CVSup, see the FreeBSD page on it at
<http://www.freebsd.org/handbook/mirrors-cvsup.html>.

=head1 Making a Release

This is a checklist that INN maintainers should go through when preparing
a new release of INN.

=over 4

=item 1.

If making a major release, branch the source tree and create a new STABLE
branch tag.  This branch will be used for minor releases based on that
major release and can be done a little while before the .0 release of that
major release.  At the same time as the branch is cut, tag the trunk with
a STABLE-<version>-branch marker tag so that it's easy to refer to the
trunk at the time of the branch.

=item 2.

Update doc/pod/news.pod and regenerate NEWS.  Be more detailed for a minor
release than for a major release.  For a major release, also add
information on how to upgrade from the last major release, including
anything special to be aware of.  (Minor releases shouldn't require any
special care when upgrading.)

=item 3.

Make sure that support/config.sub and support/config.guess are the latest
versions (from <ftp://ftp.gnu.org/gnu/config/>).  See the instructions in
L<"Configuring and Portability"> for details on how to update these files.

=item 4.

Make sure that samples/control.ctl is in sync with the master version at
<ftp://ftp.isc.org/pub/usenet/CONFIG/control.ctl>.

=item 5.

Check out a copy of the release branch.  It's currently necessary to run
configure to generate Makefile.global.  Then run C<make check-manifest>.
The only differences should be files that are generated by configure; if
there are any other differences, fix the MANIFEST.

=item 6.

Run C<make release>.  Note that you need to have a copy of svn2cl from
<http://ch.tudelft.nl/~arthur/svn2cl/> to do this; at least version 0.7
is required.  Start the ChangeLog at the time of the previous release.
(Eventually, the script will be smart enough to do this for you.)

=item 7.

Make the resulting tar file available for testing in a non-listable
directory on ftp.isc.org and announce its availability on inn-workers.
Install it on at least one system and make sure that system runs fine for
at least a few days.  This is also a good time to send out a draft of the
release announcement to inn-workers for proof-reading.

=item 8.

Generate a diff between this release and the previous release if feasible
(always for minor releases, possibly not a good idea due to the length of
the diff for major releases).

=item 9.

Move the release into the public area of the ftp site and update the
inn.tar.gz link.  Make an MD5 checksum of the release tarball and put it
on the ftp site as well, and update the inn.tar.gz.md5 link.  Put the diff
up on the ftp site as well.  Contact the ISC folks to get the release
PGP-signed.  Possibly move older releases off into the OLD directory.

=item 10.

Announce the new release on inn-announce and in news.software.nntp.

=item 11.

Tag the checked-out tree that was used for generating the release with a
release tag (INN-<version>).

=item 12.

Bump the revision number in Makefile.global.in.

=back

=head1 References

Some additional references that may be hard to find and may be of use to
people working on INN:

=over 4

=item <http://www.eyrie.org/~eagle/nntp/>

The home page for the IETF NNTP standardization effort, including links
to the IETF NNTP working group archives and copies of the latest drafts
of the new NNTP standard.  The old archived mailing list traffic contains
a lot of interesting discussion of why NNTP is the way it is.

=item <http://www.imc.org/ietf-usefor/>

The archives for the USEFOR IETF working group, the working group for the
RFC 1036 replacement (the format of Usenet articles).  Also contains a lot
of references to other relevant work, such as the RFC 822 replacement
work.

=item <http://www.mibsoftware.com/userkt/inn/dev/>

Forrest Cavalier provides several tools for following INN development at
this page and elsewhere in the Usenet RKT.  Under here is a web-accessible
checked-out copy of the current INN source tree and pointers to how to use
CVSup.

=item <http://www.sas.com/standards/large.file/>

The standards for large file support on Unix that are being generally
implemented by vendors.  INN sort of partially uses these, but a good full
audit of the code to check them should really be done and there are
occasional problems.

=item <http://v6web.litech.org/ipv6primer/>

A primer on IPv6 with pointers to the appropriate places for more
technical details as needed, useful when working on IPv6 support in INN.

=back