|
Unix Programming - Best Practices for Working with Open-Source Developers - Good Project- and Archive-Naming Practice
Good Project- and Archive-Naming Practice
As the load on maintainers of archives like ibiblio, SourceForge,
and CPAN increases, there is an increasing trend for submissions
to be processed partly or wholly by programs (rather than entirely by
a human).
This makes it more important for project and archive-file names
to fit regular patterns that computer programs can parse and
understand.
Use GNU-style names with a stem and major.minor.patch numbering.
It's helpful to everybody if your archive files all have GNU-like
names — all-lower-case alphanumeric stem prefix, followed by a hyphen,
followed by a version number, extension, and other suffixes.
A good general form of name has these parts in order:
-
project prefix
-
dash
-
version number
-
dot
-
“src” or “bin” (optional)
-
dot or dash (dot preferred)
-
binary type and options (optional)
-
archiving and compression extensions
Name stems in this style can contain hyphen or underscores to
separate syllables; dashes are actually preferred. It is good
practice to group related projects by giving the stems a common
hyphen-terminated prefix.
Let's suppose you have a project you call ‘foobar’
at major version 1, minor version or release 2, patchlevel 3. If it's
got just one archive part (presumably the sources), here's what its
names should look like like:
-
foobar-1.2.3.tar.gz
-
The source archive.
-
foobar.lsm
-
The LSM file (assuming you're submitting to ibiblio).
Please
don't
use names like these:
-
foobar123.tar.gz
-
This looks to many programs like an archive
for a project called “foobar123” with no version number.
-
foobar1.2.3.tar.gz
-
This looks to many programs like an archive
for a project called “foobar1” at version 2.3.
-
foobar-v1.2.3.tar.gz
-
Many programs think this goes with a
project called “foobar-v1”.
-
foo_bar-1.2.3.tar.gz
-
The underscore is hard for people to speak,
type, and remember.
-
FooBar-1.2.3.tar.gz
-
Unless you
like
looking like a
marketing weenie. This is also hard for people to speak, type, and
remember.
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
after
the version number. That is, please do this:
-
foobar-1.2.3.src.tar.gz
-
Sources.
-
foobar-1.2.3.bin.tar.gz
-
Binaries, type not specified.
-
foobar-1.2.3.bin.i386.tar.gz
-
i386 binaries.
-
foobar-1.2.3.bin.i386.static.tar.gz
-
i386 binaries statically linked.
-
foobar-1.2.3.bin.SPARC.tar.gz
-
SPARC binaries.
Please
don't
use names like
‘foobar-i386-1.2.3.tar.gz’, because programs have a hard
time telling type infixes (like ‘-i386’) from the
stem.
The convention for distinguishing major from minor release is
simple: you increment the patch level for fixes or minor features, the
minor version number for compatible new features, and the major
version number when you make incompatible changes.
But respect local conventions where appropriate.
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 here in late 1999.)
Look for and respect the conventions of specialized
communities and developers; for general use, follow the above
guidelines.
Try hard to choose a name prefix that is unique and easy to type.
The stem prefix should be common to all of 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.
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 index file of ibiblio
and the application index at Freshmeat. Another good place
to check is SourceForge;
do a name search there.
[an error occurred while processing this directive]
|