These guidelines describe how your distribution should look when someone downloads, retrieves and unpacks it.
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. It requires GNU tar 1.13
VERS=1.0
foobar-$(VERS).tar.gz:
tar --name-prefix='foobar-$(VERS)/' -czf foobar-$(VERS).tar.gz $(SRC)
If you have an older tar program, do something like this:
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))
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:
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.
the roadmap file, to be read first
configuration, build, and installation instructions
list of project contributers
recent project news
project history
project license terms (GNU convention)
project license terms
list of files in the distribution
plain-text Frequently-Asked-Questions document for the project
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.
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).
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).
Accordingly, it's a good idea for your project site to provide installable RPMs as well as source tarballs.
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.
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.