The Art of Unix Programming

haoji

5.
Either build/installation instructions or a pointer to a file containing same (usually INSTALL).
6.
Either a maintainers/credits list or a pointer to a file containing same (usually CREDITS).
7.
Either recent project news or a pointer to a file containing same (usually NEWS).


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
CREDITS
list of project contributers
NEWS
recent project news
HISTORY
project history
COPYING
project license terms (GNU convention)
LICENSE
project license terms
MANIFEST
list of files in the distribution

haoji

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. This elaboration of the README was developed early on at the Free
Software foundation.

Having a FAQ file 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).

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 鈥

haoji

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.

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.

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.

Good communication practice

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.

Announce to c.o.l.a and Freshmeat

Announce new releases to comp.os.linux.announce. Besides being widely read itself, this group is a major feeder
for web-based what's-new sites like Freshmeat.

Announce to a relevant topic newsgroup

Find Usenet topics group directly relevant to your application, and announce there as well. Post only where the
function of the code is relevant, and exercise restraint.

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.

Your announcement should include the URL of a project website.

haoji

Have a website

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:

l
The project charter (why it exists, who the audience is, etc).
l
Download links for the project sources.
l
Instructions on how to join the project mailing list(s).
l
A FAQ (Frequently Asked Questions) list.
l
HTMLized versions of the project documentation
l
Links to related and/or competing projects.


Some project sites even have URLs for anonymous access to the master source tree.

Refer to the website examples in Chapter 14 (Re-Use) for examples of what a well-educated project website looks
like.

Host project mailing lists

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.

If you are running a project named 鈥榝oo鈥

haoji

The logic of licenses: how to pick one

Prev Chapter 17. Open Source

Next



The logic of licenses: how to pick one

The choice of license terms involves decisions about what, if any restrictions the author wants to put
on what people do with the software.

If you want to make no restrictions at all, you should put your software in the public domain. An
appropriate way to do this would be to include something like the following text at the head of each
file:

Placed in public domain by J. Random Hacker, 2003. Share and enjoy!

If you do this, you are surrendering your copyright. Anyone can do anything they like with any part
of the text. It doesn't get any freer than this.

But very little open-source software is actually placed in the public domain, because most open-
source developers want to use their ownership of the code to ensure that it stays open.

Prev Up Next

Best practices for working with open-
source developers

Home Why you should use a standard license

haoji

Why you should use a standard license

Prev Chapter 17. Open Source

Next



Why you should use a standard license

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.

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.

Furthermore, the presence of an established interpretive tradition may prove important if
your license is ever tested in court. At time of writing (early 2003) 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. There is thus
good reason to hope that open-source community practice will be determinative when the
court system finally has to cope.

Prev Up Next

The logic of licenses: how to pick
one

Home Varieties of Open-Source
Licensing

haoji

Varieties of Open-Source Licensing

Prev Chapter 17. Open Source

Next



Varieties of Open-Source Licensing

X Consortium License

The loosest kind of free-software license is one that grants unrestricted rights to copy, use,
modify, and redistribute modified copies as long as a copy of the copyright and license terms
is retained in all modified versions.

You can find a template for the standard X Consortium license at the OSI site.

Most 鈥渟hareware鈥

haoji

The next most restrictive kind of license grants unrestricted rights to copy, use, and locally
modify. It allows redistribution of modified binaries, but restricts redistribution of modified
sources in ways intended to protect the interests of the authors and the free-software
community.

The Artistic License, devised for Perl and widely used in the Perl developer community, is of
this kind. It requires modified files to contain 鈥減rominent notice鈥

haoji

Prev Up Next

Why you should use a standard
license

Home Chapter 18. Futures

haoji

Chapter 18. Futures

Prev Part IV. Community

Next



Chapter 18. Futures

Dangers and Opportunities

Table of Contents

Essence and accident in Unix tradition
Problems in the design of Unix
A Unix file is just a big bag of bytes
File deletion is forever
The Unix API doesn't use exceptions
ioctl(2) and fcntl(2) are an embarrassment
The Unix security model may be too primitive
Unix has too many different kinds of names for things
File systems might be considered harmful



Problems in the environment of Unix
Problems in the culture of Unix
Reasons to believe


The art of prophecy is very difficult 鈥