Previous: Makefile Conventions, Up: Managing Releases


7.3 Making Releases

You should identify each release with a pair of version numbers, a major version and a minor. We have no objection to using more than two numbers, but it is very unlikely that you really need them.

Package the distribution of Foo version 69.96 up in a gzipped tar file with the name foo-69.96.tar.gz. It should unpack into a subdirectory named foo-69.96.

Building and installing the program should never modify any of the files contained in the distribution. This means that all the files that form part of the program in any way must be classified into source files and non-source files. Source files are written by humans and never changed automatically; non-source files are produced from source files by programs under the control of the Makefile.

The distribution should contain a file named README which gives the name of the package, and a general description of what it does. It is also good to explain the purpose of each of the first-level subdirectories in the package, if there are any. The README file should either state the version number of the package, or refer to where in the package it can be found.

The README file should refer to the file INSTALL, which should contain an explanation of the installation procedure.

The README file should also refer to the file which contains the copying conditions. The GNU GPL, if used, should be in a file called COPYING. If the GNU LGPL is used, it should be in a file called COPYING.LIB.

Naturally, all the source files must be in the distribution. It is okay to include non-source files in the distribution, provided they are up-to-date and machine-independent, so that building the distribution normally will never modify them. We commonly include non-source files produced by Bison, lex, TeX, and makeinfo; this helps avoid unnecessary dependencies between our distributions, so that users can install whichever packages they want to install.

Non-source files that might actually be modified by building and installing the program should never be included in the distribution. So if you do distribute non-source files, always make sure they are up to date when you make a new distribution.

Make sure that the directory into which the distribution unpacks (as well as any subdirectories) are all world-writable (octal mode 777). This is so that old versions of tar which preserve the ownership and permissions of the files from the tar archive will be able to extract all the files even if the user is unprivileged.

Make sure that all the files in the distribution are world-readable.

Don't include any symbolic links in the distribution itself. If the tar file contains symbolic links, then people cannot even unpack it on systems that don't support symbolic links. Also, don't use multiple names for one file in different directories, because certain file systems cannot handle this and that prevents unpacking the distribution.

Try to make sure that all the file names will be unique on MS-DOS. A name on MS-DOS consists of up to 8 characters, optionally followed by a period and up to three characters. MS-DOS will truncate extra characters both before and after the period. Thus, foobarhacker.c and foobarhacker.o are not ambiguous; they are truncated to foobarha.c and foobarha.o, which are distinct.

Include in your distribution a copy of the texinfo.tex you used to test print any *.texinfo or *.texi files.

Likewise, if your program uses small GNU software packages like regex, getopt, obstack, or termcap, include them in the distribution file. Leaving them out would make the distribution file a little smaller at the expense of possible inconvenience to a user who doesn't know what other files to get.