mirror of https://github.com/tLDP/LDP
moved to docbook from linuxdoc
This commit is contained in:
parent
7d232134d7
commit
2924822f0f
|
@ -0,0 +1,927 @@
|
|||
|
||||
<!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&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 (${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:
|
||||
-- >
|
||||
|
Loading…
Reference in New Issue