LDP/LDP/howto/docbook/Software-Release-Practice-HOWTO.sgml

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

<!-- Reference RFC 2026-2028? -->

<article>
<articleinfo>
<title>Software Release Practice HOWTO</title>

<author>
  <firstname>Eric</firstname>
  <othername>Steven</othername>
  <surname>Raymond</surname>
  <affiliation>
    <orgname><ulink url="http://www.tuxedo.org/~esr/">
    Thyrsus Enterprises</ulink></orgname> 
    <address>
    <email>esr@thyrsus.com</email>
    </address>
  </affiliation>
</author>
<pubdate role="cvs">$Date$</pubdate>
<releaseinfo>This is version 3.0</releaseinfo>
<copyright>
  <year>2000</year>
  <holder role="mailto:esr@thyrsus.com">Eric S. Raymond</holder> 
</copyright>
<legalnotice>
  <title>Copyright</title>
  <para>Permission is granted to copy, distribute and/or modify
  this document under the terms of the Open Publication License,
  version 2.0.</para>
</legalnotice>

<revhistory>
   <revision>
      <revnumber>3.0</revnumber>
      <date>12 August 2000</date>
      <authorinitials>esr</authorinitials>
       <revremark>
	 First DocBook version.  Advice on SourceForge and a major section
	 on documentation practice added. 
      </revremark>
   </revision>
</revhistory>

<abstract>
<para>This HOWTO describes good release practices for Linux
open-source projects.  By following these practices, you will make it
as easy as possible for users to build your code and use it, and for
other developers to understand your code and cooperate with you to
improve it.</para>

<para>This document is a must-read for novice developers.  Experienced
developers should review it when they are about to release a new
project.  It will be revised periodically to reflect the evolution of
good-practice standards.</para>
</abstract>
</articleinfo>

<sect1><title>Introduction</title>

<sect2><title>Why this document?</title>

<para>There is a large body of good-practice traditions for
open-source code that helps other people port, use, and cooperate with
developing it.  Some of these conventions are traditional in the Unix
world and predate Linux; others have developed recently in response to
particular new tools and technologies such as the World Wide
Web.</para>

<para>This document will help you learn good practice.  It is organized into
topic sections, each containing a series of checklist items.  Think of
these as a pre-flight checklist for your software distribution.</para>

</sect2>
<sect2><title>New versions of this document</title>

<para>This document will be posted monthly to the newsgroups <ulink
url="News:comp.os.linux.answers">comp.os.linux.answers</ulink>.  You
can also view the latest version of this HOWTO on the World Wide Web
via the URL <ulink
url="http://www.linuxdoc.org/LDP/HOWTO/Software-Release-Practice.html">
http://www.linuxdoc.org/LDP/HOWTO/Software-Release-Practice.html</ulink>.
</para>

<para>Feel free to mail any questions or comments about this HOWTO to 
Eric S. Raymond, <email>esr@snark.thyrsus.com</email>.</para> 

</sect2>
</sect1>
<sect1><title>Good project- and archive- naming practice</title>

<para>As the load on maintainers of archives like Metalab, the PSA
site and CPAN increases, there is an increasing trend for submissions
to be processed partly or wholly by programs (rather than entirely by
a human).</para>

<para>This makes it more important for project and archive-file names
to fit regular patterns that computer programs can parse and
understand.</para>

<sect2><title>Use GNU-style names with a stem and major.minor.patch numbering.</title>

<para>It's helpful to everybody if your archive files all have GNU-like
names -- all-lower-case alphanumeric stem prefix, followed by a dash,
followed by a version number, extension, and other suffixes.</para>

<para>Let's suppose you have a project you call `foobar' at version 1,
release 2, level 3.  If it's got just one archive part (presumably the
sources), here's what its names should look:</para>

<variablelist>
<varlistentry>
<term>foobar-1.2.3.tar.gz</term>
<listitem><para>The source archive</para></listitem>
</varlistentry>
<varlistentry>
<term>foobar.lsm</term>
<listitem><para>The LSM file (assuming you're submitting to Metalab).</para></listitem>
</varlistentry>
</variablelist>

<para>Please <emphasis>don't</emphasis> use these:</para>

<variablelist>
<varlistentry>
<term>foobar123.tar.gz</term>
<listitem><para>This looks to many programs like an archive
for a project called`foobar123' with no version number.</para></listitem>
</varlistentry>
<varlistentry>
<term>foobar1.2.3.tar.gz</term>
<listitem><para>This looks to many programs like an archive
for a project called `foobar1' at version 2.3.</para></listitem>
</varlistentry>
<varlistentry>
<term>foobar-v1.2.3.tar.gz</term>
<listitem><para>Many programs think this goes with a
project called `foobar-v1'.</para></listitem>
</varlistentry>
<varlistentry>
<term>foo_bar-1.2.3.tar.gz</term>
<listitem><para>The underscore is hard for people to speak,
type, and remember.</para></listitem>
</varlistentry>
<varlistentry>
<term>FooBar-1.2.3.tar.gz</term>
<listitem><para>Unless you <emphasis>like</emphasis> looking like a
marketing weenie.  This is also hard for people to speak, type, and 
remember.</para></listitem>
</varlistentry>
</variablelist>

<para>If you have to differentiate between source and binary archives, or
between different kinds of binary, or express some kind of build
option in the file name, please treat that as a file extension to go
<emphasis>after</emphasis> the version number. That is, please do this:</para>

<variablelist>
<varlistentry>
<term>foobar-1.2.3.src.tar.gz</term>
<listitem><para>sources</para></listitem>
</varlistentry>
<varlistentry>
<term>foobar-1.2.3.bin.tar.gz</term>
<listitem><para> binaries, type not specified</para></listitem>
</varlistentry>
<varlistentry>
<term>foobar-1.2.3.bin.ELF.tar.gz</term>
<listitem><para>ELF binaries</para></listitem>
</varlistentry>
<varlistentry>
<term>foobar-1.2.3.bin.ELF.static.tar.gz</term>
<listitem><para>ELF binaries statically linked</para></listitem> 
</varlistentry>
<varlistentry>
<term>foobar-1.2.3.bin.SPARC.tar.gz</term>
<listitem><para>SPARC binaries</para></listitem>
</varlistentry>
</variablelist>

<para>Please <emphasis>don't</emphasis> use names like
`foobar-ELF-1.2.3.tar.gz', because programs have a hard time telling
type infixes (like `-ELF') from the stem.</para>

<para>A good general form of name has these parts in order:</para>

<orderedlist>
<listitem><para>project prefix</para></listitem> 
<listitem><para>dash</para></listitem> 
<listitem><para>version number</para></listitem> 
<listitem><para>dot</para></listitem> 
<listitem><para>"src" or "bin" (optional)</para></listitem> 
<listitem><para>dot or dash (dot preferred)</para></listitem> 
<listitem><para>binary type and options (optional)</para></listitem> 
<listitem><para>archiving and compression extensions</para></listitem> 
</orderedlist>

</sect2>
<sect2><title>But respect local conventions where appropriate</title>

<para>Some projects and communities have well-defined conventions for names and
version numbers that aren't necessarily compatible with the above advice.
For instance, Apache modules are generally named like mod_foo, and have
both their own version number and the version of Apache with which they
work.  Likewise, Perl modules have version numbers that can be treated as
floating point numbers (e.g., you might see 1.303 rather than 1.3.3), and
the distributions are generally named Foo-Bar-1.303.tar.gz for version
1.303 of module Foo::Bar. (Perl itself, on the other hand, switched to
using the conventions described un this document in late 1999.)</para>

<para>Look for and respect the conventions of specialized
communities and developers; for general use, follow the above
guidelines.</para>

</sect2>
<sect2><title>Try hard to choose a name prefix that is unique and easy to type</title>

<para>The stem prefix should be common to all a project's files, and it
should be easy to read, type, and remember.  So please don't use
underscores.  And don't capitalize or BiCapitalize without extremely
good reason -- it messes up the natural human-eyeball search order and
looks like some marketing weenie trying to be clever.</para>

<para>It confuses people when two different projects have the same
stem name.  So try to check for collisions before your first release.
Two good places to check are the <ulink
url="http://metalab.unc.edu/pub/Linux">index file of Metalab</ulink>
and the appindex at <ulink
url="http://www.freshmeat.net">Freshmeat</ulink>.  Another good place
to check is <ulink url="http://www.sourceforge.net">SourceForge</ulink>;
do a name search there.</para>

</sect2>
</sect1>
<sect1><title>Good licensing and copyright practice: the theory</title>

<para>The license you choose defines the social contract you wish to set up
among your co-developers and users.  The copyright you put on the software
will function mainly as a legal assertion of your right to set license
terms on the software and derivative works of the software.</para>

<sect2><title>Open source and copyrights</title>

<para>Anything that is not public domain has a copyright, possibly more than
one.  Under the Berne Convention (which has been U.S. law since 1978),
the copyright does not have to be explicit.  That is, the authors of a
work hold copyright even if there is no copyright notice.</para>

<para> Who counts as an author can be very complicated, especially for
software that has been worked on by many hands.  This is why licenses
are important.  By setting out the terms under which material can be
used, they grant rights to the users that protect them from arbitrary
actions by the copyright holders.</para>

<para>In proprietary software, the license terms are designed to
protect the copyright.  They're a way of granting a few rights to
users while reserving as much legal territory is possible for the
owner (the copyright holder).  The copyright holder is very important,
and the license logic so restrictive that the exact technicalities of
the license terms are usually unimportant.</para>

<para>In open-source software, the situation is usually the exact opposite;
the copyright exists to protect the license.  The only rights the
copyright holder always keeps are to enforce the license.  Otherwise,
only a few rights are reserved and most choices pass to the user.  In
particular, the copyright holder cannot change the terms on a copy you
already have.  Therefore, in open-source software the copyright holder
is almost irrelevant -- but the license terms are very important.</para>

<para>Normally the copyright holder of a project is the current
project leader or sponsoring organization.  Transfer of the project to
a new leader is often signaled by changing the copyright holder.
However, this is not a hard and fast rule; many open-source projects
have multiple copyright holders, and there is no instance on record of
this leading to legal problems.</para>

<para>Some projects choose to assign copyright to the Free Software Foundation,
on the theory that it has an interest in defending open source and lawyers
available to do it.</para>

</sect2>
<sect2><title>What qualifies as open source</title>

<para>For licensing purposes, we can distinguish several different
kinds of rights that a license may convey.  Rights to <emphasis>copy
and redistribute</emphasis>, rights to <emphasis>use</emphasis>,
rights to <emphasis>modify for personal use</emphasis>, and rights to
<emphasis>redistribute modified copies</emphasis>.  A license may
restrict or attach conditions to any of these rights.</para>

<para>The <ulink url="http://www.opensource.org">Open Source
Initiative</ulink> is the result of a great deal of thought about what
makes software ``open source'' or (in older terminology) ``free''.
Its constraints on licensing require that:</para>

<orderedlist>
<listitem><para>An unlimited right to copy be granted.</para></listitem> 
<listitem><para>An unlimited right to use be granted.</para></listitem> 
<listitem><para>An unlimited right to modify for personal use be granted.</para></listitem> 
</orderedlist>

<para>The guidelines prohibit restrictions on redistribution of
modified binaries; this meets the needs of software distributors, who
need to be able to ship working code without encumbrance.  It allows
authors to require that modified sources be redistributed as pristine
sources plus patches, thus establishing the author's intentions and an
``audit trail'' of any changes by others.</para>

<para>The OSD is the legal definition of the `OSI Certified Open Source'
certification mark, and as good a definition of ``free software'' as
anyone has ever come up with.  All of the standard licenses (MIT, BSD,
Artistic, and GPL/LGPL) meet it (though some, like GPL, have other
restrictions which you should understand before choosing it).</para>

<para>Note that licenses which allow noncommercial use only do
<emphasis>not</emphasis> qualify as open-source licenses, even if they
are decorated with ``GPL'' or some other standard license.  They
discriminate against particular occupations, persons, and groups.
They make life too complicated for CD-ROM distributors and others
trying to spread open-source software commercially.</para>

</sect2>
</sect1>
<sect1><title>Good licensing and copyright practice: the practice</title>

<para>Here's how to translate the theory above into practice:</para>

<sect2><title>Make yourself or the FSF the copyright holder</title>

<para>In some cases, if you have a sponsoring organization behind you with
lawyers, you might wish to give copyright to that organization.</para>

</sect2>
<sect2><title>Use a license conformant to the Open Source Definition</title>

<para>The Open Source Definition is the community gold standard for
licenses.  The OSD is not a license itself; rather, it defines a
minimum set of rights that a license must guarantee in order to be
considered an open-source license.  The OSD, and supporting materials,
may be found at the web site of the <ulink
url="http://www.opensource.org">Open Source Initiative</ulink>.</para>

</sect2>
<sect2><title>Don't write your own license if you can possibly avoid it.</title>

<para>The widely-known OSD-conformant licenses have well-established interpretive
traditions.  Developers (and, to the extent they care, users) know what
they imply, and have a reasonable take on the risks and tradeoffs they
involve.  Therefore, use one of the standard licenses carried on the OSI
site if at all possible.</para>

<para>If you must write your own license, be sure to have it certified
by OSI.  This will avoid a lot of argument and overhead.  Unless
you've been through it, you have no idea how nasty a licensing
flamewar can get; people become passionate because the licenses are
regarded as almost-sacred covenants touching the core values of the
open-source community.</para>

<para>Furthermore, the presence of an established interpretive tradition may
prove important if your license is ever tested in court.  At time of 
writing (mid-2000) there is no case law either supporting or invalidating
any open-source license.  However, it is a legal doctrine (at least in
the U.S., and probably in other common-law countries such as England
and the rest of the British Commonwealth) that courts are supposed to 
interpret licenses and contracts according to the expectations and
practices of the community in which they originated.</para>

</sect2>
</sect1>
<sect1><title>Good development practice</title>

<para>Most of these are concerned with ensuring portability, not only across
Linuxes but to other Unixes as well.  Being portable to other Unixes 
is not just a worthy form of professionalism and hackerly politeness, 
it's valuable insurance against future changes in Linux itself.</para>

<para>Finally, other people <emphasis>will</emphasis> try to build
your code on non-Linux systems; portability minimizes the number of
annoying perplexed email messages you will get.</para>

<sect2><title>Write either pure ANSI C or a portable scripting language</title>

<para>For portability and stability, you should write either in ANSI C or a
scripting language that is guaranteed portable because it has just one
cross-platform implementation.</para>

<para>Scripting languages that qualify include Python, Perl, Tcl,
Emacs Lisp, and PHP.  Plain old shell does <emphasis>not</emphasis>
qualify; there are too many different implementations with subtle
idiosyncracies, and the shell environment is subject to disruption by
user customizations such as shell aliases.</para>

<para>Java holds promise as a portable language, but the Linux-available 
implementations are still scratchy and poorly integrated with Linux.
Java is still a bleeding-edge choice, though one likely to become more
popular as it matures.</para>

</sect2>
<sect2><title>Follow good C portability practices</title>

<para>If you are writing C, do feel free to use the full ANSI features --
including function prototypes, which will help you spot cross-module
inconsistancies.  The old-style K&amp;R compilers are history.</para>

<para>On the other hand, do <emphasis>not</emphasis> assume that GCC-specific 
features such as the `-pipe' option or nested functions are available.
These will come around and bite you the second somebody ports to a
non-Linux, non-GCC system.</para>

</sect2>
<sect2><title>Use autoconf/automake/autoheader</title>

<para>If you're writing C, use autoconf/automake/autoheader to handle
portability issues, do system-configuration probes, and tailor your
makefiles.  People building from sources today expect to be able to
type "configure; make" and get a clean build -- and rightly so.</para>

</sect2>
<sect2><title>Sanity-check your code before release</title>

<para>If you're writing C, test-compile with -Wall and clean up the
errors at least once before each release.  This catches a surprising
number of errors.  For real thoroughness, compile with -pedantic as
well.</para>

<para>If you're writing Perl, check your code with perl -c (and maybe
-T, if applicable).  Use perl -w and 'use strict' religiously.  (See
the Perl documentation for discussion.)</para>

</sect2>
<sect2><title>Sanity-check your documentation and READMEs before release</title>

<para>Run a spell-checker on them.  If you look like you can't spell and
don't care, people will assume you code is sloppy and careless too.</para>

</sect2>
</sect1>
<sect1><title>Good distribution-making practice</title>

<para>These guidelines describe how your distribution should look when
someone downloads, retrieves and unpacks it.</para>

<sect2><title>Make sure tarballs always unpack into a single new directory</title>

<para>The single most annoying mistake newbie developers make is to build
tarballs that unpack the files and directories in the distribution into
the current directory, potentially stepping on files already located there.
<emphasis>Never do this!</emphasis></para>

<para>Instead, make sure your archive files all have a common directory part
named after the project, so they will unpack into a single top-level 
directory directly <emphasis>beneath</emphasis> the current one.</para>

<para>Here's a makefile trick that, assuming your distribution directory is
named `foobar' and SRC contains a list of your distribution files,
accomplishes this.</para>

<programlisting>
foobar-$(VERS).tar.gz:
	@ls $(SRC) | sed s:^:foobar-$(VERS)/: >MANIFEST
	@(cd ..; ln -s foobar foobar-$(VERS))
	(cd ..; tar -czvf foobar/foobar-$(VERS).tar.gz `cat foobar/MANIFEST`)
	@(cd ..; rm foobar-$(VERS))
</programlisting>

</sect2>
<sect2><title>Have a README</title>

<para>Have a file called <filename>README</filename> or
<filename>READ.ME</filename> that is a roadmap of your source
distribution.  By ancient convention, this is the first file intrepid
explorers will read after unpacking the source.</para>

<para>Good things to have in the README include:</para>

<orderedlist>
<listitem><para>A brief description of the project.</para></listitem>
<listitem><para>A pointer to the project website (if it has 
one)</para></listitem>
<listitem><para>Notes on the developer's build environment and
potential portability problems.</para></listitem>
<listitem><para>A roadmap describing important files and subdirectories.</para></listitem> 
<listitem><para>Either build/installation instructions or a pointer to a file
containing same (usually <filename>INSTALL</filename>).</para></listitem>
<listitem><para>Either a maintainers/credits list or a pointer to a
file containing same (usually
<filename>CREDITS</filename>).</para></listitem>
<listitem><para>Either recent project news or a pointer to a file
containing same (usually <filename>NEWS</filename>).</para></listitem>
</orderedlist>

</sect2>
<sect2><title>Respect and follow standard file naming practices</title>

<para>Before even looking at the README, your intrepid explorer will
have scanned the filenames in the top-level directory of your unpacked
distribution.  Those names can themselves convey information.  By
adhering to certain standard naming practices, you can give the
explorer valuable clues about what to look in next.</para>

<para>Here are some standard top-level file names and what they mean.  Not
every distribution needs all of these.</para>

<variablelist>
<varlistentry>
<term>README or READ.ME</term>
<listitem><para>the roadmap file, to be read first</para></listitem>
</varlistentry>

<varlistentry>
<term>INSTALL</term>
<listitem><para> configuration, build, and installation instructions</para></listitem>
</varlistentry>

<varlistentry>
<term>CREDITS</term>
<listitem><para> list of project contributers</para></listitem>
</varlistentry>

<varlistentry>
<term>NEWS</term><listitem>
<para> recent project news</para></listitem>
</varlistentry>

<varlistentry>
<term>HISTORY</term>
<listitem><para> project history</para></listitem>
</varlistentry>

<varlistentry>
<term>COPYING</term>
<listitem><para> project license terms (GNU convention)</para></listitem>
</varlistentry>

<varlistentry>
<term>LICENSE</term>
<listitem><para> project license terms</para></listitem>
</varlistentry>

<varlistentry>
<term>MANIFEST</term>
<listitem><para> list of files in the distribution</para></listitem>
</varlistentry>

<varlistentry>
<term>FAQ</term>
<listitem><para> plain-text Frequently-Asked-Questions document for
the project</para></listitem>
</varlistentry>

<varlistentry>
<term>TAGS</term>
<listitem><para> generated tag file for use by Emacs or vi</para></listitem>
</varlistentry>
</variablelist>

<para>Note the overall convention that filenames with all-caps names are
human-readable metainformation about the package, rather than build
components.</para>

<para>Having a FAQ can save you a lot of grief.  When a question about the
project comes up often, put it in the FAQ; then direct users to read the
FAQ before sending questions or bug reports.  A well-nurtured FAQ can
decrease the support burden on the project maintainers by an order of
magnitude or more.</para>

<para>Having a HISTORY or NEWS file with timestamps in it for each release
is valuable.  Among other things, it may help establish prior art if
you are ever hit with a patent-infringement lawsuit (this hasn't
happened to anyone yet, but best to be prepared).</para>

</sect2>
<sect2><title>Design for Upgradability</title>

<para>Your software will change over time as you put out new releases.  Some
of these changes will not be backward-compatible.  Accordingly, you
should give serious thought to designing your installation layouts so
that multiple installed versions of your code can coexist on the same
system.  This is especially important for libraries -- you can't 
count on all your client programs to upgrade in lockstep with your
API changes.</para>

<para>The Emacs, Python, and Qt projects have a good convention for handling
this; version-numbered directories.  Here's how an installed Qt
library hierarchy looks (&dollar;{ver} is the version number):</para>

<screen>
/usr/lib/qt
/usr/lib/qt-${ver}
/usr/lib/qt-${ver}/bin          # Where you find moc
/usr/lib/qt-${ver}/lib          # Where you find .so
/usr/lib/qt-${ver}/include      # Where you find header files
</screen>

<para>With this organization, you can have multiple versions
coexisting.  Client programs have to specify the library version they
want, but that's a small price to pay for not having the interfaces
break on them.</para>

</sect2>
<sect2><title>Provide RPMs</title>

<para>The de-facto standard format for installable binary packages is
that used by the Red Hat Package manager, RPM.  It's featured in the
most popular Linux distribution, and supported by effectively all
other Linux distributions (except Debian and Slackware; and Debian can
install from RPMs).</para>

<para>Accordingly, it's a good idea for your project site to provide
installable RPMs as well as source tarballs.</para>

<para>It's also a good idea for you to include in your source tarball the RPM
spec file, with a production that makes RPMs from it in your Makefile.
The spec file should have the extension `.spec'; that's how the rpm -t
option finds it in a tarball.</para>

<para>For extra style points, generate your spec file with a shellscript that
automatically plugs in the correct version number by analyzing the Makefile
or a version.h.</para>

<para>Note: if you supply source RPMs, use BuildRoot to make the program be
built in /tmp or /var/tmp.  If you don't, during the course of running
the make install part of your build, the install will install the
files in the real final places. This will happen even if there are
file collisions, and even if you didn't want to install the package at
all. When you're done, the files will have been installed and your
system's RPM database will not know about it. Such badly behaved
SRPMs are a minefield and should be eschewed.</para>

</sect2>
</sect1>
<sect1><title>Good documentation practice</title>

<para>The most important good documentation practice is to actually
write some!  Too many programmers omit this.  But here are two good
reasons to do it:</para>

<orderedlist>
<listitem><para>
<emphasis>Your documentation can be your design document.</emphasis>
The best time to write it is before you type a single line of code,
while you're thinking out what you want to do.  You'll find that the
process of describing the way you want your program to work in natural
language focuses your mind on the high-level questions about  what it should
do and how it should work.  This may save you a lot of effort later.
</para></listitem>
<listitem><para>
<emphasis>Your documentation is an advertisement for the 
quality of your code.</emphasis>
Many people take poor, scanty, or illiterate documentation for a program as
a sign that the programmer is sloppy or careless of potential users' needs.
Good documentation, on the other hand, conveys a message of intelligence
and professionalism. If your program has to compete with other programs,
better make sure your documentation is at least as good as theirs lest
potential users write you off without a second look.
</para></listitem>
</orderedlist>

<para>This HOWTO wouldn't be the place for a course on technical writing
even if that were practical.  So we'll focus here on the formats and tools
available for composing and rendering documentation.</para>

<para>Though Unix and the open-source community have a long tradition of
hosting powerful document-formatting tools, the plethora of different
formats has meant that documentation has tended to be fragmented and
difficult for users to browse or index in a coherent way.
We'll summarize the uses, strengths, and weaknesses of the common 
documentation formats. Then we'll make some recommendations for good
practice.</para>

<sect2><title>Good practice in the present</title>

<para>Here are the documentation markup formats now in widespread use among
open-source developers.  When we speak of "presentation" markup, we mean
markup that controls the document's appearance explicitly (such as a font
change).  When we speak of "structural" markup, we mean markup that
describes the logical structure of the document (like a section break or
emphasis tag.)  And when we speak of "indexing", we mean the process 
of extracting from a collection of documents a searchable collection
of topic pointers that users can employ to reliably find material
of interest across the entire collection.</para>

<variablelist>
<varlistentry>
<term>man pages</term>
<listitem>
<para>The most most common format, inherited from Unix, a primitive form of
presentation markup.  The <command>man(1)</command> command provides a
pager and stone-age search facility.  No support for images or hyperlinks
or indexing. Renders to Postscript for printing fairly well.  Doesn't
render to HTML at all well (essentially as flat text).  Tools are
preinstalled on all Linux systems.</para>

<para>Man page format is not bad for command summaries or short reference
documents intended to jog the memory of an experienced user.  It starts to
creak under the strain for programs with complex interfaces and many
options, and collapses entirely if you need to maintain a set of documents
with rich cross-references (the markup has no support for
hyperlinks).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>HTML</term>
<listitem>
<para>Increasingly common since the Web exploded in 1993-1994. Markup is
partly structural, mostly presentation. Browseable through any web browser.
Good support for images and hyperlinks.  Limited built-in facilities for
indexing, but good indexing and search-engine technologies exist and are
widely deployed.  Renders to Postscript for printing pretty well.  HTML
tools are now universally available.</para>

<para>HTML is very flexible and suitable for many kinds of documentation.
Actually, it's <emphasis>too</emphasis> flexible; it shares with man page
format the problem that it's hard to index automatically because a lot of the 
markup describes presentation rather than document structure.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Texinfo</term>
<listitem>
<para>Texinfo is the documentation format used by the Free Software
Foundation. It's a set of macros on top of the powerful TeX formatting
engine. Mostly structural, partly presentation.  Browseable through Emacs
or a standalone <command>info</command> program.  Good support for
hyperlinks, none for images.  Good indexing for both print and on-line
forms; when you install a Texinfo document, a pointer to it is
automatically added to a browsable "dir" document listing all the Texinfo
documents on your system.  Renders to excellent Postscript and useable
HTML.  Texinfo tools are preinstalled on most Linux systems, and available
at the <ulink url="http://www.gnu.org">Free Software Foundation</ulink>
website.</para>

<para>Texinfo is a good design, quite usable for typesetting books as well
as small on-line documents, but like HTML it's a sort of amphibian -- the
markup is part structural, part presentation, and the presentation part
creates problems for rendering. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>DocBook</term>
<listitem>
<para>DocBook is a large, elaborate markup format based on SGML (more
recent versions on XML).  Unlike the other formats described here it is
entirely structural with no presentation markup.  Excellent support for
images and hyperlinks.  Good support for indexing.  Renders well to HTML,
acceptably to Postscript for printing (quality is improving as the tools
evolve).  Tools and documentation are available at the <ulink
url="http://www.docbook.org/">DocBook website</ulink>.</para>

<para>DocBook is excellent for large, complex documents; it was designed
specifically to support technical manuals and rendering them in multiple
output formats.  Its drawbacks are complexity, a not entirely mature
(though rapidly improving) toolset, and introductory-level documentation
that is scanty and (too often) highly obfuscated.</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>
<sect2><title>Good practice for the future</title>

<para>In July of 2000 representatives from several important open-source
project groups (including GNOME, KDE, the Free Software Foundation, the
Linux Documentation Project, and the Open Source Initiative) held a summit
conference in Monterey, California. The goal was to try and settle on
common practices and common documentation interchange formats, so that a
much richer and more unified body of documentation can evolve.</para>

<para>Concretely, the goal everyone has in view is to support a kind of
documentation package which, when installed on a system, is immediately
integrated into a rich system-wide index of documents in such a way that
they can all be browsed through a uniform interface and searched as a
unit. From the steps GNOME and KDE have already taken in this direction, 
it was already understood that this would require a structural rather 
than presentation markup standard.</para>

<para>The meeting endorsed a trend which has been clear for a while; key
open-source projects are moving or have already moved to DocBook as a
master format for their documentation.</para>

<para>The participants also settled on using the `Dublin core' metadata
format (an international standard developed by librarians concerned with
the indexing of digital material) to support document indexing; details of
that are still being worked out, and will probably result in some additions
to the DocBook markup to support embedding Dublin Core metadata in 
DocBook documents.</para>

<para>The direction is clear; more use of Docbook, with auxiliary standards
that support automatically indexing Docbook documents based on their index
tags and Dublin core metadata.  There are pieces still missing from this
picture, but they will be filled in.  The older presentation-based markups'
days are numbered.  (This HOWTO was moved to DocBook in August
2000.)</para>

<para>Thus, people starting new open-source projects will be ahead of the
curve, and probably saving themselves a nasty conversion process later, if
they go with DocBook as a master format from the beginning.</para>

</sect2>
</sect1>
<sect1><title>Good communication practice</title>

<para>Your software and documentation won't do the world much good if
nobody but you knows it exists.  Also, developing a visible presence for
the project on the Internet will assist you in recruiting users and
co-developers.  Here are the standard ways to do that.</para>

<sect2><title>Announce to c.o.l.a and Freshmeat</title>

<para>Announce new releases to <ulink url="news:comp.os.linux.announce">
comp.os.linux.announce</ulink>.  Besides being widely read itself,
this group is a major feeder for web-based what's-new sites like
<ulink url="http://www.freshmeat.net">Freshmeat</ulink>.</para>

</sect2>
<sect2><title>Announce to a relevant topic newsgroup</title>

<para>Find USENET topics group directly relevant to your application,
and announce there as well.  Post only where the
<emphasis>function</emphasis> of the code is relevant, and exercise
restraint.</para>

<para>If (for example) you are releasing a program written in Perl that queries
IMAP servers, you should certainly post to comp.mail.imap.  But you
should probably not post to comp.lang.perl unless the program is also
an instructive example of cutting-edge Perl techniques.</para>

<para>Your announcement should include the URL of a project website.</para>

</sect2>
<sect2><title>Have a website</title>

<para>If you intend try to build any substantial user or developer community
around your project, it should have a website.  Standard things to have
on the website include:</para>

<itemizedlist>
<listitem><para>The project charter (why it exists, who the audience is, etc).</para></listitem>
<listitem><para>Download links for the project sources.</para></listitem>
<listitem><para>Instructions on how to join the project mailing list(s).</para></listitem>
<listitem><para>A FAQ (Frequently Asked Questions) list.</para></listitem>
<listitem><para>HTMLized versions of the project documentation</para></listitem>
<listitem><para>Links to related and/or competing projects.</para></listitem>
</itemizedlist>

<para>Some project sites even have URLs for anonymous access to the master
source tree.</para>

</sect2>
<sect2><title>Host project mailing lists</title>

<para>It's standard practice to have a private development list
through which project collaborators can communicate and exchange
patches.  You may also want to have an announcements list for people
who want to be kept informed of the project's process.</para>

<para>If you are running a project named `foo'.
your developer list might be foo-dev or foo-friends; your announcement
list might be foo-announce.</para>

</sect2>
<sect2><title>Release to major archives</title>

<para>For the last several years, the <ulink
url="http://www.metalab.unc.edu/pub/Linux/">Metalab archive</ulink> has
been the most important interchange location for Linux software.</para>

<para>Since it was launched in fall 1999, 
<ulink url="http://www.sourceforge.net">SourceForge</ulink> has exploded
in popularity.  It is not just an archive and distribution site, though
you can use it that way.  It is an entire free project-hosting service that
tries to offer a complete set of tools for open-source development groups --
web and archive space, mailing lists, bug-tracking, chat forums, CVS
repositories, and other services.</para>

<para>Other important locations include:</para>

<itemizedlist>
<listitem>
<para>the <ulink url="http://www.python.org">Python Software Activity</ulink>
site (for software written in Python).</para>
</listitem>
<listitem>
<para>the <ulink url="http://language.perl.com/CPAN">CPAN</ulink>, the
Comprehensive Perl Archive Network, (for software written in Perl).</para>
</listitem>
</itemizedlist>

</sect2>
</sect1>
<sect1><title>Good project-management practice</title>

<para>Managing a project well when all the participants are volunteers presents
some unique challenges.  This is too large a topic to cover in a HOWTO.
Fortunately, there are some useful white papers available that will help you
understand the major issues.</para>

<para>For discussion of basic development organization and the 
release-early-release-often `bazaar mode', see <ulink url="http://www.tuxedo.org/~esr/writings/cathedral-bazaar/">The Cathedral and
the Bazaar</ulink>.</para>

<para>For discussion of motivational psychology, community customs,
and conflict resolution, see <ulink
url="http://www.tuxedo.org/~esr/writings/homesteading/">Homesteading
the Noosphere</ulink>.</para>

<para>For discussion of economics and appropriate business models, see 
<ulink url="http://www.tuxedo.org/~esr/writings/magic-cauldron/">The Magic Cauldron</ulink>.</para>

<para>These papers are not the last word on open-source development.  But they
were the first serious analyses to be written, and have yet to be
superseded (though the author hopes they will be somesday).</para>

</sect1>
</article>

<!--
The following sets edit modes for GNU EMACS
Local Variables:
fill-column:75
compile-command: "mail -s \"HOWTO update\" ldp-submit@lists.linuxdoc.org <Software-Release-Practice-HOWTO.sgml"
End:
End:
-- >