INN commit: trunk/doc/pod (hacking.pod)
INN Commit
Russ_Allbery at isc.org
Thu May 21 16:32:58 UTC 2009
Date: Thursday, May 21, 2009 @ 09:32:58
Author: iulius
Revision: 8482
* Mention Trac instead of ViewVC.
* Add a link to nightly snapshots and update other links.
* Add POD commands (especially B<>, C<> and F<>).
* Explain how to update install-sh.
* Update the section on how to make a release.
Modified:
trunk/doc/pod/hacking.pod
-------------+
hacking.pod | 355 +++++++++++++++++++++++++++++++---------------------------
1 file changed, 194 insertions(+), 161 deletions(-)
Modified: hacking.pod
===================================================================
--- hacking.pod 2009-05-20 20:10:04 UTC (rev 8481)
+++ hacking.pod 2009-05-21 16:32:58 UTC (rev 8482)
@@ -13,47 +13,48 @@
<http://inn.eyrie.org/svn/>
-or view it with ViewVC at:
+or view it with Trac source browser at:
- <http://inn.eyrie.org/viewcvs>
+ <http://inn.eyrie.org/trac/browser/>
You will need S<autoconf 2.61> or later to use the development tree. After
checking out the tree, run C<./autogen> to generate the necessary autoconf
files.
-Nightly snapshots and repository dumps suitable for use with svk will be
-available soon.
+Nightly snapshots can be found at:
+ <ftp://ftp.isc.org/isc/inn/snapshots/>
+
=head1 Configuring and Portability
All INN code should be written expecting S<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
+as F<< <stdarg.h> >>, string concatenation, C<#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
+checking for standard behavior in F<configure> and supplying replacements for
standard functions that are missing.
When there is a conflict between S<ANSI C> and C99, INN code should be
-written expecting C99 and autoconf used to patch up the differences.
+written expecting C99 and B<autoconf> used to patch up the differences.
-Try to avoid using #ifdef and the like in the middle of code as much as
+Try to avoid using C<#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
+include them in B<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.ac> and the additional macros in
-the F<m4> directory, and F<include/config.h.in> is generated by autoheader
-from F<configure.ac>. At configure time, configure generates
+generated by B<autoconf> from F<configure.ac> and the additional macros in
+the F<m4> directory, and F<include/config.h.in> is generated by B<autoheader>
+from F<configure.ac>. At configure time, F<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.ac>.
-The autoconf manual (available using info autoconf if you have autoconf
-and the GNU info utilities installed on your system) is a valuable
+All modifications to F<configure> should instead be made to F<configure.ac>.
+The B<autoconf> manual (available using C<info autoconf> if you have B<autoconf>
+and the GNU B<info> utilities installed on your system) is a valuable
reference when making any modifications.
To regenerate F<configure>, just run C<autoconf>. To regenerate
@@ -65,24 +66,28 @@
At the time of this writing, S<Autoconf 2.61> or later is required.
-The supporting files for autoconf are in the F<support> subdirectory,
+The supporting files for B<autoconf> are in the F<support> subdirectory,
including the files F<config.guess> and F<config.sub> to determine the
system name and F<ltmain.sh> for libtool support. The latter file
-comes from the libtool distribution; the canonical version of the former
+comes from the libtool distribution available from
+L<http://www.gnu.org/software/libtool/>; the canonical version of the former
two are available from L<ftp://ftp.gnu.org/gnu/config/> (which currently
redirects to L<http://git.savannah.gnu.org/gitweb/?p=config.git;a=tree>).
In addition, F<m4/libtool.m4> is just a copy of F<libtool.m4> from the
-libtool distribution. (Using libtool without using automake requires
+libtool distribution. (Using libtool without using B<automake> requires
a few odd hacks.) New versions should be checked in periodically when
available. There are no INN-specific modifications to those files except
for F<ltmain.sh> which recognizes the additional B<-B> flag that INN's
-B<install-sh> script uses.
+B<install-sh> script uses. This script should also be updated at the
+same time; it similarly contains local modifications in order to support
+the additional B<-B> flag, as well as a few other changes mentioned
+in a comment at the beginning of the file.
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.
+quite right for C<make -j> using libtool.
=head1 Documentation
@@ -117,12 +122,12 @@
S<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
+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.
+various flags right for B<pod2text> or B<pod2man>.
=head1 Error Handling
@@ -137,7 +142,7 @@
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 (mesage_log_stderr) prints to
+default one. The default error handler (message_log_stderr) prints to
stderr, prepending the value of message_program_name if it's set to
something other than NULL. Several other error handlers are available,
particularly including ones that use syslog. See
@@ -157,7 +162,7 @@
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
+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
@@ -210,33 +215,33 @@
=head1 Test Suite
-The test suite for INN is located in the tests directory and is just
+The test suite for INN is located in the F<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
+program that tests some part of INN, put it in a directory under F<tests>
named after the part of INN it's testing, 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
+line saying C<ok n> or C<not ok n> where C<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
+that wasn't compiled into INN, the test program should output C<ok n #
+skip>.) Add any rules necessary to build the test to F<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.
+test to F<tests/TESTS>, without the F<.t> ending.
-For C tests, you probably want to use the functions in libtest.c
-(prototypes in libtest.h) to handle all of the output. For shell script
+For C tests, you probably want to use the functions in F<libtest.c>
+(prototypes in F<libtest.h>) to handle all of the output. For shell script
tests, see the existing tests for some helpful shell functions.
-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".
+One naming convention: to distinguish more easily between for example
+F<lib/error.c> (the implementation) and F<tests/lib/error-t.c> (the test suite),
+we add F<-t> to the end of the test file names. So F<tests/lib/error-t.c> is
+the source that compiles into an executable F<tests/lib/error.t> which is run
+by putting a line in F<tests/TESTS> of just C<lib/error>.
-Note that tests don't have to be written in C; in fact, lib/xmalloc.t is
+Note that tests don't have to be written in C; in fact, F<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
@@ -246,65 +251,65 @@
=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
+All INN makefiles include F<Makefile.global> at the top level, and only that
+makefile is a F<configure> substitution target. This has the disadvantage
+that F<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
+F<configure> run much faster and allowing one to run C<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
+All INN makefiles should also set C<$(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.
+programs like B<fixscript> and libtool so that the same macros (set in
+F<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
+least for directories with lots of separate programs. The C<ALL> variable
+holds all the files that should be generated, C<EXTRA> those additional files
+that were generated by F<configure>, and C<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
+variables by F<Makefile.global>, and these should be used for all file
+installations. See the comment blocks in F<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/distclean, 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). These
-rules should be present and empty in those directories where they don't
-apply.
+Each subdirectory makefile should have the targets C<all> (the default),
+C<clean>, C<clobber>/C<distclean>, C<install>, C<tags>, and C<profiled>.
+The C<tags> target generates B<vi> tags files, and the C<profiled> target
+generates a profiling version of the programs (although this hasn't been
+tested much). 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 $(LIBCC)
-and $(LIBLD) (which will be set as appropriate in Makefile.global).
+the compile steps for all library source, should be done through C<$(LIBCC)>
+and C<$(LIBLD)> (which will be set as appropriate in F<Makefile.global>).
=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
+F<configure>-time information and configuration information from F<inn.conf> are
+set by the B<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.
+interpretor and adding a line to load the appropriate B<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
+F<support/fixscript>, built by F<configure>, does this. It takes a F<.in> file
+and generates the final script (removing the F<.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.)
+it is, with code to load the B<innshellvars> appropriate for that
+interpretor. (If invoked with B<-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
+Scripts should use B<innshellvars> (via B<fixscript>) to get the right path and
+the right variables whenever possible, rather than having F<configure>
substitute values in them. Any values needed at run-time should instead
-be available from all of the different innshellvars.
+be available from all of the different B<innshellvars>.
As for Perl, the C<INN::Config> module has the same features as
F<innshellvars.pl> (only kept for compatibility reasons with old scripts
@@ -316,9 +321,9 @@
=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
+built as part of INN (the utility B<libinn> library and the B<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
+F<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:
@@ -326,11 +331,11 @@
#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
+The first picks up all defines generated by B<autoconf> and is necessary for
+types that may not be present on all systems (I<uid_t>, I<pid_t>, I<size_t>,
+I<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. It also includes "inn/defines.h" and "inn/options.h", which
+information. It also includes F<inn/defines.h> and F<inn/options.h>, which
pick up additional support macros and compile-time configuration.
The second is portably equivalent to:
@@ -349,11 +354,11 @@
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
+include F<clibrary.h> rather than trying to duplicate the B<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
+source files in F<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
+be easily used in other projects that use B<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
@@ -362,7 +367,7 @@
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
+F<include/portable> and familiarize yourself with them and use them where
appropriate.
Another frequently included header file is F<inn/libinn.h>, which among other
@@ -375,19 +380,19 @@
F<inn/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 innconf_read() and use the global innconf
+F<inn.conf>; instead, call innconf_read() and use the global I<innconf>
structure.
-Other files in include are interfaces to particular bits of INN library
+Other files in F<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.
+(such as F<clibrary.h>). All of the installed headers will live in
+F<include/inn> and be installed in a subdirectory named F<inn> in the configured
+F<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
@@ -398,8 +403,8 @@
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
+namespace, particularly for installed header files in F<include/inn>. All
+symbols defined by a header file should ideally begin with C<INN_>, C<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.
@@ -421,7 +426,7 @@
=item *
Write in regular S<ANSI C> whenever possible. Use the normal ANSI and POSIX
-constructs and use autoconf or portability wrappers to fix things up
+constructs and use B<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
@@ -443,7 +448,7 @@
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.
+replacements in F<lib> for systems that don't have them.
If you have to use a string copying routine that doesn't nul-terminate,
use memcpy instead. Avoid introducing any uses of strcpy, strcat,
@@ -452,18 +457,18 @@
=item *
-Avoid #ifdef and friends whenever possible. Particularly avoid using them
+Avoid C<#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
+magic in header files or in portability code in F<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;
+generic function and provide two separate implementations using C<#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,
+them to either C<0> or C<1> (never use C<#define> without a second argument),
+you can use the preprocessor define in a regular if statement rather than
+using C<#if> or C<#ifdef>. Make use of this instead of C<#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
@@ -474,7 +479,7 @@
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.
+is provided in F<lib/buffer.c>.
=item *
@@ -488,7 +493,7 @@
=item *
Use a roughly BSD indentation style but with four-space indents. This
-means no space before the parens around function arguments, open brace on
+means no space before the parenthesis around function arguments, open brace on
the same line as if/while/for, and close and open brace on the same line
as else).
@@ -506,7 +511,7 @@
multiline comment. */
Comments before functions saying what they do are nice to have. In
-general, the RCS/SVN Id tag is on the first line of each source file since
+general, the RCS/SVN C<Id> tag is on the first line of each source file since
it's useful to know when a file was last modified.
=item *
@@ -524,7 +529,7 @@
=item *
-It's better to always put the body of an if statement on a separate line,
+It's better to always put the body of an C<if> statement on a separate line,
even if it's only a single line. In other words, write:
if (p != NULL)
@@ -535,7 +540,7 @@
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
+like B<purecov> will count the second example above as a single line and
won't notice if the condition always evaluates the same way.
=item *
@@ -547,9 +552,9 @@
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.
+underlying data type. Also avoid using the C<_t> suffix for any type; all
+types ending in C<_t> are reserved by POSIX. For typedefs of function
+pointer types, a suffix of C<_func> usually works.
This style point is currently widely violated inside of INN itself; INN
originally made extensive use of typedefs.
@@ -557,24 +562,24 @@
=item *
When noting something that should be improved later, add a comment
-containing "FIXME:" so that one can easily grep for such comments.
+containing C<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:
+INN's indentation style roughly corresponds to that produced by GNU
+S<B<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
+Unfortunately, B<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
+B<indent> routinely to enforce a consistant coding style, but B<indent> isn't
quite ready for that.
For users of emacs cc-mode, use the "bsd" style but with:
@@ -589,7 +594,7 @@
; Use only spaces when indenting or centering, no tabs.
(setq-default indent-tabs-mode nil)
-in your ~/.emacs file.
+in your F<~/.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
@@ -604,80 +609,115 @@
=item 1.
-If making a major release, branch the source tree by creating a new
-directory under branches in Subversion named after the major release.
-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.
+Make sure that F<support/config.guess>, F<support/config.sub>,
+F<support/install-sh>, F<support/ltmain.sh> and libtool m4 files
+(F<libtool.m4>, F<ltoptions.m4>, F<ltsugar.m4>, F<ltversion.m4>
+and F<lt~obsolete.m4>) are the latest versions. See the instructions
+in L<"Configuring and Portability"> for details on how to update these files.
=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
+Make sure that F<samples/control.ctl> is in sync with the master version at
+L<ftp://ftp.isc.org/pub/usenet/CONFIG/control.ctl>.
+
+=item 3.
+
+Update F<doc/pod/news.pod> and regenerate F<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>.
+Bump the revision number in F<doc/FAQ> so that it is included in
+the release.
=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.
+If making a major release, branch the source tree by creating a new
+directory under F<branches> in Subversion named after the major release.
+This branch will be used for minor releases based on that major release
+and can be done a little while before the C<.0> release of that major
+release.
+ svn copy -r ZZZZ -m "Branch Y.Y.0 release." file:///srv/svn/inn/trunk file:///srv/svn/inn/branches/Y.Y
+
=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.)
+Check out a copy of the release branch. It's currently necessary to run
+C<configure> to generate F<Makefile.global>. Then run C<make check-manifest>.
+The only differences should be files that are generated by F<configure>; if
+there are any other differences, fix the F<MANIFEST> file.
=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.
+Run C<make release> for a final release, C<support/mksnapshot BETA b1>
+for the first beta version of a new release, or C<support/mksnapshot RC rc1>
+for the first release candidate version of a new release. Note that you
+need to have a copy of B<svn2cl> from L<http://ch.tudelft.nl/~arthur/svn2cl/>
+to do this; at least version 0.7 is required. Start the F<ChangeLog> at the
+time of the previous release. (Eventually, the script will be smart enough
+to do this for you.)
+Check that the F<ChangeLog> file is correct; otherwise, regenerate it or
+manually edit it. Then run again C<make release> or any other command
+you used.
+
=item 8.
+Generate an MD5 checksum of the release tarball.
+
+ md5sum inn-Y.Y.Y.tar.gz > inn-Y.Y.Y.tar.gz.md5
+
+=item 9.
+
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).
+the diff for major releases). You will need the tar file of the previous
+release for the comparison.
-=item 9.
+ diff -Nurp inn-X.X.X inn-Y.Y.Y > inn-X.X.X-Y.Y.Y.diff
+ gzip inn-X.X.X-Y.Y.Y.diff
-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.
+Make the resulting tar file, along with its MD5 checksum and the possible
+diff from the previous release, available for testing in the F<testing>
+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 11.
-Tag the checked-out tree that was used for generating the release with a
-release tag by copying it to tags/<version> in Subversion.
+Move the release into the public area of the ftp site and update the
+F<inn.tar.gz> link. Also put the diff and the MD5 checksum on the ftp
+site and update the F<inn.tar.gz.md5> link. Contact the ISC folks to
+get the release PGP-signed and update the F<inn.tar.gz.asc> link.
+Possibly move older releases off into the F<OLD> directory.
=item 12.
-Bump the revision number in Makefile.global.in.
+After the ISC web site has been updated with links towards the new
+release, send an announce on inn-announce and in news.software.nntp
+(with a possible crosspost to news.admin.announce).
+=item 13.
+
+Tag the checked-out tree that was used for generating the release with a
+release tag by copying it to F<tags> in Subversion.
+
+ svn copy -r ZZZZ -m "Tag Y.Y.Y release." file:///srv/svn/inn/branches/Y.Y file:///srv/svn/inn/tags/Y.Y.Y
+
+=item 14.
+
+Bump revision numbers to reflect the one of the following release,
+especially in F<doc/pod/install.pod> and F<doc/pod/readme.pod>
+for major releases, F<configure.ac> and F<Makefile.global.in>
+for both minor and major releases. The release versions in the
+Trac wiki should also be updated.
+
=back
=head1 References
@@ -687,36 +727,29 @@
=over 4
-=item <http://www.eyrie.org/~eagle/nntp/>
+=item L<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/>
+=item L<http://www.imc.org/ietf-usefor/>
The archives for the USEFOR IETF working group, the working group for the
-S<RFC 1036> replacement (the format of Usenet articles). Also contains a lot
-of references to other relevant work, such as the S<RFC 822> replacement
-work.
+S<RFC 1036> replacement (the format of Usenet articles), now published as
+S<RFC 5536> and S<RFC 5537>. Also contains a lot of references to other
+relevant work. Another useful link is L<http://www.eyrie.org/~eagle/usefor/>.
-=item <http://www.mibsoftware.com/userkt/inn/dev/>
+=item L<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. However, please note that INN development now uses Subversion.
-=item <http://www.sas.com/standards/large.file/>
+=item L<http://tools.ietf.org/html/draft-lutchann-ipv6-intro-00>
-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.
More information about the inn-committers
mailing list