CLASS="SECT1" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" >

1. Introduction

Skimming through freshmeat.net provides mountains of reasons for this HOWTO's existence--the Internet is littered with excellently written and useful programs that have faded away into the universe of free software forgottenness. This dismal scene made me ask myself, "Why?"

This HOWTO tries to do a lot of things (probably too many), but it can't answer that question and won't attempt it. What this HOWTO will attempt to do is give your Free Software project a fighting chance--an edge. If you write a piece of crap that no one is interested in, you can read this HOWTO until you can recite it in your sleep and your project will probably fail. Then again, you can write a beautiful, relevant piece of software and follow every instruction in this HOWTO and your software may still not make it. Sometimes life is like that. However, I'll go out a limb and say that if you write a great, relevant pieces of software and ignore the advise in this HOWTO, you'll probably fail more often.

A lot of the information in this HOWTO is best called common sense. Of course, as any debate on interfaces will prove, what is common sense to some programmers proves totally unintuitive to others. After explaining bits and pieces of this HOWTO to Free Software developers on several occasions, I realized that writing this HOWTO might provide a useful resource and a forum for programmers to share ideas about what has and has not worked for them.

As anyone involved in any of what seems like an unending parade of ridiculous intellectual property clashes will attest to, a little bit of legalese proves important.

1.1. Copyright Information

This document is copyrighted (c) 2000 Benjamin "Mako" Hill and is distributed under the terms of the GNU Free Documentation License.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found in Appendix A.

1.2. Disclaimer

No liability for the contents of this documents can be accepted. Use the concepts, examples and other content at your own risk. As this is a new edition of this document, there may be errors and inaccuracies, that may of course be damaging to your project (and potentially your system). Proceed with caution, and although this is highly unlikely, the author(s) does not take any responsibility for that.

All copyrights are held by their by their respective owners, unless specifically noted otherwise. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark.

Naming of particular products or brands should not be seen as endorsements.

1.3. New Versions

This version is the part of the third pre-release cycle of this HOWTO. It is written to be released to developers for critique and brainstorming. Please keep in mind that this version of the HOWTO is still in an infant stage and will continue to be revised extensively.

The latest version number of this document should always be listed on the projects homepage hosted by yukidoke.org.

The newest version of this HOWTO will always be made available at the same website, in a variety of formats:

1.4. Credits

In this version I have the pleasure of acknowledging:

Fellow Debian developer Martin Michlmayr and Vivek Venugopalan who sent me information and links to extremely interesting articles. I've added both to the bibliography and I've added information from each into the HOWTO. Thanks to Andrew Shugg who pointed out several errors in the document. Also, a big thanks to Sung Wook Her (AKA RedBaron) who is doing the first translation of the HOWTO into Korean. I've been happy to see that people have enjoyed and benefited from the HOWTO so far.

Older thanks that I don't want to take out yet include: Josh Crawford, Andy King, and Jaime Davila who all read through this in entirety and gave me feedback that has helped me make changes and improvements to this document. I can't thank you guys enough for your help. An extra "Thank You" goes to Andy King who who read through this several times and submitted patches to make life easier for me.

Karl Fogel, the author of Open Source Development with CVS published by the Coriolis Open Press. Large parts of his book are available on the web. 225 pages of the book are available under the GPL and constitute the best tutorial on CVS I've ever seen. The rest of the book covers, "the challenges and philosophical issues inherent in running an Open Source project using CVS." The book does a good job of covering some of the subjects brought up in this HOWTO and much more. The book's website has information on ordering the book and provides several translations of the chapters on CVS. If you are seriously interested in running a Free Software project, you want this book. I tried to mention Fogel in sections of this HOWTO where I knew I was borrowing directly from his ideas. If I missed any, I'm sorry. I'll try and have those fixed in future versions.

Karl Fogel can be reached at

Also providing support material, and inspiration for this HOWTO is Eric S. Raymond for his prolific, consistent, and carefully crafted arguments and Lawrence Lessig for reminding me of the importance of Free Software. Additionally, I want to thank every user and developer involved with the Debian Project. The project has provided me with a home, a place to practice free software advocacy, a place to make a difference, a place to learn from those who have been involved with the movement much longer than I, and proof of a free software project that definitely, definitely works.

Above all, I want to thank Richard Stallman for his work at the Free Software Foundation and for never giving up. Stallman provides and articulates the philosophical basis that attracts me to free software and that drives me toward writing a document to make sure it succeeds. RMS can always be emailed at .

1.5. Feedback

Feedback is always and most certainly welcome for this document. Without your submissions and input, this document wouldn't exist. Do you feel that something is missing? Don't hesitate to contact me to have me write a chapter, section, or subsection or to write one yourself. I want this document to be a product of the Free Software development process that it heralds and I believe that its ultimate success will be rooted in its ability to do this. Please send your additions, comments, and criticisms to the following email address: .

1.6. Translations

I know that not everyone speaks English. Translations are nice and I'd love for this HOWTO to gain the kind of international reach afforded by translated versions.

I've been contacted by a reader who promises a translation into Korean. However, this HOWTO is still young and other than the promise of Korean, English is all that is currently available. If you would like to help with or do a translation, you will gain my utmost respect and admiration and you'll get to be part of a cool process. If you are at all interested, please don't hesitate to contact me at: .