man-pages/MAINTAINING

One day, it won't be me any more, so to make life easier for the next
maintainer: some tips on how to maintain the Linux manual pages

Get the source code
===================

History matters.  The manual pages document not just the current 
state of the Linux kernel and glibc, but also how it has changed 
over time.  So, set aside a few gigabytes of disk space...

Kernel source code
------------------

You can find nearly every kernel release ever made at 
www.kernel.org.  At the very least, you should:

-- keep up-to-date trees for the 2.2.x, 2.4.x, and 2.6.x
   kernels.  These trees can be grepped to look for 
   differences across major kernel versions.

-- Keep a directory that contains every minor release patch ever made.
   (e.g. patch-2.6.15, patch-2.6.0, patch-2.5.38, patch-2.4.1, 
   patch-2.4.0-test7, patch-1.2.16, etc.)  Grepping these patches
   can help determine in which minor release a kernel
   change occurred, e.g.:

        grep 'epoll_create' patch-*

   to see when epoll_create was added as a system call.

-- Keep all the ChangeLogs too -- they can be checked to look for
   explanations of patches found via grepping as described in the 
   previous point.

Glibc source code
-----------------

Same story as the kernel.  

-- Keep up to date trees for 2.0.x, 2.1.x, 2.2.x, 2.3.x, 2.4.x.

-- Keep diff files for all minor releases of the glibc tree.
   As with kernel, these can be grepped to help determine
   when a particular change occurred in glibc.

A lot of glibc tarballs can be found at http://ftp.gnu.org/gnu/glibc/.
A lot of older tarballs can be found at 
ftp://ftp.win.tue.nl/pub/linux-local/libc.archive/.


Keeping up
==========

One of the biggest challenges is keeping up to date with changes in 
the kernel and glibc.  A few ways to do this are:

Mailing lists
-------------

Linux Kernel (LKML)
    This list contains patches, bug reports, and general discussions 
    about the kernel.  To subscribe, send a message containing the 
    following *body* to majordomo@vger.kernel.org:
    
        subscribe linux-kernel

    The problem with this list is that the volume is extremely high,
    so keeping track of it all would require a lot of time.  

    http://www.kernel.org/ provides the locations of a few searchable 
    archives of this mailing list.
    
Websites
--------

These websites are useful because they in part include attempts 
by others to summarise LKML traffic.

http://lwn.net/
    The weekly kernel page is especially useful, since it summarises
    a lot of current and planned changes to the kernel.

http://wiki.kernelnewbies.org/LinuxChanges
    Summarises major internal and interface changes for each
    kernel release (starting sometime in the 2.6.x series).

http://kerneltrap.org/news
    Reports on recent changes in various free kernels.
    
Kernel releases
---------------

When a new minor kernel release is made (e.g., 2.6.19), scan the
patch and Changelog, to see what important changes there have been.
This is quite a big job, and pretty much impossible to do thoroughly,
unless doing man-pages is your full time job, but a bit of scripting 
can help (e.g., to discard device driver stuff and 
architecture-specific stuff other than for (say) x86 and PPC).

Glibc releases
--------------

Just as for the kernel, when a new glibc release comes out.

Distribution bug tracking systems
---------------------------------

Debian makes it easy for upstream maintainers to subscribe to bug 
reports for manual pages.  To do this, visit 
http://packages.qa.debian.org/ and look for the Debian source package 
"manpages".  A current list of Debian "manpages" bug reports can be 
found at http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=manpages.

Debian even provides an email interface which allows an upstream 
maintainer to manipulate Debian bug reports (using the "tags"
command; see http://www.debian.org/Bugs/server-control.

Perhaps some other distributions do the same, but Debian is the 
only one I know about so far.


Testing New Features
====================

Test programs
-------------

Writing test programs (in C) is an essential part of writing manual 
pages.  It verifies the author's understanding of what is being 
documented and also finds bugs in the kernel and glibc.  In some
cases, example programs are also suitable for inclusion in the manual
pages themselves.

Testing new kernel features
---------------------------

To follow the development curve closely, download release candidate (rc) 
kernels from http://www.kernel.org/pub/linux/kernel/v2.6/testing/.
Build and install the kernel, and test new features with test 
programs.  Since the declarations of new system calls probably
won't yet be in your (g)libc, the use of syscall() or _syscallN()
may be required; see the intro(2) manual page.


All the world is not Linux
==========================

It is not enough to document what Linux does.  Programmers
writing portable applications need to know about places where
Linux differs from other Unix implementations, and about
places where it doesn't adhere to standards.

Test programs
-------------

If in doubt about portability, write a test program and run it 
on a few other systems.  As a starting point, testing say Solaris, 
FreeBSD, and HP-UX is likely to reveal most of the range of 
differences that occur on other implementations.  Bonus points
for testing on other BSDs, on AIX, etc.

If you don't have access to other systems, there are shell
guest accounts for various systems available on the net.  See, 
especially, http://www.testdrive.hp.com/.

Standards
---------

Join the Austin group.  It's free.  See 
http://www.opengroup.org/austin/.

Get electronic copies of current and past Unix standards, especially
the current POSIX.1/SUSv3 standard.  Note also that section 3p
of the manual pages includes manual pages containing the
specifications for all functions specified in POSIX.1-2001 (e.g.,
try "man 3p stat").

Other standards to look out for are SUSv1, SUSv2, and the SVID
(System V Interface Definition), all of which are available in
electronic form.

And get the C99 standard.  There are electronic versions of near 
final drafts available on the net, if one searches on the net.

And have a look at the LSB, http://www.freestandards.org/.

Other Manual Pages
------------------

Get manual pages for as many other Unix systems (including past and
current versions) as you can find.  Check those manual pages to see
what differences there are from Linux.  They'll also provide ideas
about topics that should covered in corresponding Linux manual pages.

Glibc info
----------

Sometimes there is useful information to be found in the info(1)
document for a particular function (if the info document exists...).
Always worth checking...

Header files on other implementations
-------------------------------------

It can be handy to have a set of /usr/include trees from various 
other implementations.  Grepping all of these trees can give some 
clues about interfaces that are/aren't present on other Unix 
implementations.


Being a good free software citizen
==================================

Reporting kernel and glibc bugs
-------------------------------

Testing kernel and glibc features while writing manual pages will 
inevitably uncover bugs.  Report them.  

For the kernel, a report can either go into the bugzilla 
(http://bugzilla.kernel.org), or, if the report is of general interest 
(e.g., a significant bug a new system call), it may be worthwhile
submitting a note the author of the system call and CCing LKML.

Bug reports for glibc go here: http://sourceware.org/bugzilla.
If you are feeling in a good mood, you could even report bugs in
glibc info documents there.


Some History
============

The man-pages project was begun in 1993, by Rik Faith, who created
releases 1.0 through to 1.5.

The man-pages maintainer par excellence was Andries Brouwer, who
took over in June 1995, and continued for more than nine years, 
creating releases 1.6 through to 1.70.

The current maintainer, Michael Kerrisk, took over in November 2004, 
starting with release 2.00.