7. Good distribution-making practice

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

7.1. Make sure tarballs always unpack into a single new directory

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.
Never do this!

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 beneath the current one.

Here's a makefile trick that, assuming your distribution directory is
named `foobar' and SRC contains a list of your distribution files,
accomplishes this. SRC may also contain names of subdirectories to
be included whole.

7.2. Have a README

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

Good things to have in the README include:

A brief description of the project.

A pointer to the project website (if it has
one)

Notes on the developer's build environment and
potential portability problems.

A roadmap describing important files and subdirectories.

Either build/installation instructions or a pointer to a file
containing same (usually INSTALL).

Either a maintainers/credits list or a pointer to a
file containing same (usually
CREDITS).

Either recent project news or a pointer to a file
containing same (usually NEWS).

7.3. Respect and follow standard file naming practices

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.

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

README or READ.ME

the roadmap file, to be read first

INSTALL

configuration, build, and installation instructions

AUTHORS

list of project contributers.

An older, still-acceptable convention for this is to name it CREDITS

NEWS

recent project news

HISTORY

project history

COPYING

project license terms (GNU convention)

LICENSE

project license terms

MANIFEST

list of files in the distribution

FAQ

plain-text Frequently-Asked-Questions document for
the project

TAGS

generated tag file for use by Emacs or vi

Note the overall convention that filenames with all-caps names are
human-readable metainformation about the package, rather than build
components (TAGS is an exception to the first, but not to the second).

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.

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).

7.4. Design for Upgradability

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.

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):

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.

7.5. Provide checksums

Provide checksums with your binaries (tarballs, RPMs, etc.). This
will allow people to verify that they haven't been corrupted or had
Trojan-horse code inserted in them.

While there are several commands you can use for this purpose (such
as sum and cksum) it is best to use a
cryptographically-secure hash function. The GPG package provides this
capability via the —detach-sign option; so does the GNU
command md5sum.

For each binary you ship, your project web page should list
the checksum and the command you used to generate it.