2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
9 <title>Free Software Project Management HOWTO</title>
12 <firstname>Benjamin</firstname>
13 <othername>Mako</othername>
14 <surname>Hill</surname>
17 <email>mako@atdot.cc</email>
24 <revnumber>v0.3.3</revnumber>
25 <date>22 August 2008</date>
26 <authorinitials>bch</authorinitials>
30 <revnumber>v0.3.2</revnumber>
31 <date>15 April 2002</date>
32 <authorinitials>bch</authorinitials>
36 <revnumber>v0.3.1</revnumber>
37 <date>18 June 2001</date>
38 <authorinitials>bch</authorinitials>
42 <revnumber>v0.3</revnumber>
43 <date>5 May 2001</date>
44 <authorinitials>bch</authorinitials>
48 <revnumber>v0.2.1</revnumber>
49 <date>10 April 2001</date>
50 <authorinitials>bch</authorinitials>
54 <revnumber>v0.2</revnumber>
55 <date>8 April 2001</date>
56 <authorinitials>bch</authorinitials>
60 <revnumber>v0.01</revnumber>
61 <date>27 March 2001</date>
62 <authorinitials>bch</authorinitials>
63 <revremark>Initial Release</revremark>
69 <primary>fswd</primary>
73 This HOWTO is designed for people with experience in programming
74 and some skills in managing a software project but who are new to
75 the world of free software. This document is meant to act as a
76 guide to the non-technical aspects of free software project
77 management and was written to be a crash course in the people
78 skills that aren't taught to commercial coders but that can make
79 or break a free software project.
85 <!-- Section1: intro -->
88 <title>Introduction</title>
91 <primary>fswd!introduction</primary>
95 Skimming through freshmeat.net provides mountains of reasons for this
96 HOWTO's existence--the Internet is littered with excellently
97 written and useful programs that have faded away into the universe
98 of free software forgottenness. This dismal scene made me ask
103 This HOWTO tries to do a lot of things (probably too many), but it
104 can't answer that question and won't attempt it. What this HOWTO
105 will attempt to do is give your Free Software project a fighting
106 chance--an edge. If you write a piece of crap that no one is
107 interested in, you can read this HOWTO until you can recite it in
108 your sleep and your project will probably fail. Then again, you can
109 write a beautiful, relevant piece of software and follow every
110 instruction in this HOWTO and your software may still not make
111 it. Sometimes life is like that. However, I'll go out a limb and
112 say that if you write a great, relevant pieces of software and
113 ignore the advise in this HOWTO, you'll probably fail <emphasis>
114 more often</emphasis>.
118 A lot of the information in this HOWTO is best called common
119 sense. Of course, as any debate on interfaces will prove, what is
120 common sense to some programmers proves totally unintuitive to
121 others. After explaining bits and pieces of this HOWTO to Free
122 Software developers on several occasions, I realized that writing
123 this HOWTO might provide a useful resource and a forum for
124 programmers to share ideas about what has and has not worked for
129 As anyone involved in any of what seems like an unending parade of
130 ridiculous intellectual property clashes will attest to, a little
131 bit of legalese proves important.
134 <!-- Section2: copyright -->
136 <sect2 id="copyright">
137 <title>Copyright Information</title>
140 This document is copyrighted (c) 2000-2008 Benjamin Mako Hill and is
141 distributed under the terms of the <citetitle>GNU Free
142 Documentation License</citetitle>.
146 Permission is granted to copy, distribute and/or modify this
147 document under the terms of the <link
148 linkend="fdl"><citetitle>GNU Free Documentation
149 License</citetitle></link>, Version 1.2 or any later version
150 published by the Free Software Foundation with no Invariant
151 Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy
152 of the license can be found in <xref linkend="fdl">.
156 <!-- Section2: disclaimer -->
158 <sect2 id="disclaimer">
159 <title>Disclaimer</title>
162 No liability for the contents of this documents can be accepted.
163 Use the concepts, examples and other content at your own risk. As
164 this is a new edition of this document, there may be errors and
165 inaccuracies, that may of course be damaging to your project (and
166 potentially your system). Proceed with caution, and although this
167 is highly unlikely, the author(s) does not take any responsibility
172 All copyrights are held by their by their respective owners, unless
173 specifically noted otherwise. Use of a term in this document
174 should not be regarded as affecting the validity of any trademark
179 Naming of particular products or brands should not be seen
185 <!-- Section2: newversions-->
187 <sect2 id="newversions">
188 <title>New Versions</title>
191 This version is the part of the third pre-release cycle of this
192 HOWTO. It is written to be released to developers for critique and
193 brainstorming. While the HOWTO is now several years old, please keep
194 in mind that this version of the HOWTO is still in an "early" stage
195 and will continue to be revised extensively.
199 The latest version number of this document should always be listed
200 on <ulink url="http://mako.cc/projects/howto">the projects
205 The newest version of this HOWTO will always be made available at
206 the same website, in a variety of formats:
214 <ulink url="http://mako.cc/projects/howto/FreeSoftwareProjectManagement-HOWTO/t1.html">HTML</ulink>.
221 <ulink url="http://mako.cc/projects/howto/FreeSoftwareProjectManagement-HOWTO.html">HTML (single page)</ulink>.
227 <ulink URL="http://mako.cc/projects/howto/FreeSoftwareProjectManagement-HOWTO.txt">plain text</ulink>.
233 <ulink url="http://mako.cc/projects/howto/FreeSoftwareProjectManagement-HOWTO.ps.gz">Compressed postscript</ulink>.
239 <ulink url="http://mako.cc/projects/howto/FreeSoftwareProjectManagement-HOWTO.sgml.gz">Compressed SGML source</ulink>.
246 <!-- Section2: credits -->
249 <title>Credits</title>
252 In this version I have the pleasure of acknowledging:
255 <para>Fellow Debian developers Martin Michlmayr and Vivek
256 Venugopalan who sent me information and links to extremely
257 interesting articles. I've added both to the bibliography and I've
258 added information from each into the HOWTO. Thanks to Andrew Shugg
259 who pointed out several errors in the document. Also, a big thanks
260 to Sung Wook Her (AKA RedBaron) who is doing the first translation
261 of the HOWTO into Korean. I've been happy to see that people have
262 enjoyed and benefited from the HOWTO so far.</para>
265 Older thanks that I don't want to take out yet include: Josh
266 Crawford, Andy King, and Jaime Davila who all read through this in
267 entirety and gave me feedback that has helped me make changes and
268 improvements to this document. I can't thank you guys enough for
269 your help. An extra <quote>Thank You</quote> goes to Andy King who
270 who read through this several times and submitted patches to make
275 Karl Fogel, the author of <citetitle>Open Source Development with
276 CVS</citetitle> published by the Coriolis Open Press. Large parts
277 of his book are available <ulink
278 url="http://cvsbook.red-bean.com">on the web</ulink>. 225 pages of
279 the book are available under the GPL and constitute the best
280 tutorial on CVS I've ever seen. The rest of the book covers,
281 <quote>the challenges and philosophical issues inherent in running
282 an Open Source project using CVS.</quote> The book does a good job
283 of covering some of the subjects brought up in this HOWTO and much
284 more. <ulink url="http://cvsbook.red-bean.com">The book's
285 website</ulink> has information on ordering the book and provides
286 several translations of the chapters on CVS. If you are seriously
287 interested in running a Free Software project, you want this
288 book. I tried to mention Fogel in sections of this HOWTO where I
289 knew I was borrowing directly from his ideas. If I missed any, I'm
290 sorry. I'll try and have those fixed in future versions.
294 Karl Fogel can be reached at <email>kfogel (at) red-bean (dot)
299 Also providing support material, and inspiration for this HOWTO is
300 Eric S. Raymond for his prolific, consistent, and carefully
301 crafted arguments and Lawrence Lessig for reminding me of the
302 importance of Free Software. Additionally, I want to thank every
303 user and developer involved with the <ulink
304 url="http://www.debian.org">Debian Project</ulink>. The project
305 has provided me with a home, a place to practice free software
306 advocacy, a place to make a difference, a place to learn from
307 those who have been involved with the movement much longer than I,
308 and proof of a free software project that definitely, definitely
313 Above all, I want to thank <emphasis>Richard Stallman</emphasis>
314 for his work at the Free Software Foundation and for never giving
315 up. Stallman provides and articulates the philosophical basis that
316 attracts me to free software and that drives me toward writing a
317 document to make sure it succeeds. RMS can always be emailed at
318 <email>rms (at) gnu (dot) org</email>.
323 <!-- Section2: feedback -->
325 <sect2 id="feedback">
326 <title>Feedback</title>
329 Feedback is always and most certainly welcome for this
330 document. Without your submissions and input, this document
331 wouldn't exist. Do you feel that something is missing? Don't
332 hesitate to contact me to have me write a chapter, section, or
333 subsection or to write one yourself. I want this document to be a
334 product of the Free Software development process that it heralds
335 and I believe that its ultimate success will be rooted in its
336 ability to do this. Please send your additions, comments, and
337 criticisms to the following email address:
338 <email>mako@atdot.cc</email>.
342 <!-- Section2: translations -->
344 <sect2 id="translations">
345 <title>Translations</title>
348 I know that not everyone speaks English. Translations are nice and
349 I'd love for this HOWTO to gain the kind of international reach
350 afforded by translated versions.
354 This HOWTO has graciously translated into German by Robert F.
355 Schmitt. That copy is accessible in the following formats:
361 <ulink url="http://mako.cc/projects/howto/FreeSoftwareProjectManagement-HOWTO.DE.html">HTML (single page)</ulink>.
367 <ulink url="http://mako.cc/projects/howto/FreeSoftwareProjectManagement-HOWTO.DE.rstl">Restructured Text Source</ulink>.
373 If you would like to help with or do a translation, you will gain my
374 utmost respect and admiration and you'll get to be part of a cool
375 process. If you are at all interested, please don't hesitate to
376 contact me at: <email>mako@atdot.cc</email>.
381 <!-- Section1: intro: END -->
383 <!-- Section1: starting -->
385 <sect1 id="starting">
386 <title>Starting a Project</title>
389 <primary>fswd!starting</primary>
392 With very little argument, the beginning is the most difficult
393 period in a project's life to do successful free software project
394 management. Laying a firm foundation will determine whether your
395 project flourishes or withers away and dies. It is also the subject
396 that is of most immediate interest to anyone reading this document
401 Starting a project involves a dilemma that you as a developer must
402 try and deal with: no potential user for your program is interested
403 in a program that doesn't work, while the development process that
404 you want to employ holds involvement of users as imperative.
408 It is in these dangerous initial moments that anyone working to
409 start a free software project must try and strike a balance along
410 these lines. One of the most important ways that someone trying to
411 start a project can work toward this balance is by establishing a
412 solid framework for the development process through some of the
413 suggestions mentioned in this section.
417 <!-- Section2: chooseproject-->
419 <sect2 id="chooseproject">
420 <title>Choosing a Project</title>
423 If you are reading this document, there's a good chance you
424 already have an idea for a project in mind. Chances are also
425 pretty good that it fills a perceived gap by doing something that
426 no other free software project does or by doing something in a way
427 that is unique enough to necessitate a brand new piece of
431 <sect3 id=identifyidea>
432 <title>Identify and articulate your idea</title>
434 Eric S. Raymond writes about how free software projects start in
436 url="http://catb.org/~esr/writings/cathedral-bazaar/"><quote>The
437 Cathedral and the Bazaar,</quote></ulink> which comes as required
438 reading for any free software developer. It is available online .
442 In <quote>The Cathedral and the Bazaar,</quote> Raymond tells us
443 that: <quote>every good work of software starts by scratching
444 a developers itch.</quote> Raymond's now widely accepted
445 hypothesis is that new free software programs are written, first
446 and foremost, to solve a specific problem facing the developer.
450 If you have an idea for a program in mind, chances are good that
451 it targets a specific problem or <quote>itch</quote> you want to
452 see scratched. <emphasis>This idea is the project.</emphasis>
453 Articulate it clearly. Write it out. Describe the problem you
454 will attack in detail. The success of your project in tackling a
455 particular problem will be tied to your ability to identify that
456 problem clearly early on. Find out exactly what it is that you
457 want your project to do.
461 Monty Manley articulates the importance of this initial step in
462 an essay, <quote><ulink
463 url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
464 Projects the Open Source Way.</ulink></quote> As the next section
465 will show, there is <emphasis>a lot</emphasis> of work that needs
466 to be done before software is even ready to be coded. Manley
467 says, <quote>Beginning an OSS project properly means that a
468 developer must, first and foremost, avoid writing code too
473 <sect3 id=evalulateidea>
474 <title>Evaluate your idea</title>
477 In evaluating your idea, you need to first ask yourself a few
478 questions. This should happen before you move any further
479 through this HOWTO. Ask yourself: <emphasis>Is the free software
480 development model really the right one for your
485 Obviously, since the program scratches your itch, you are
486 definitely interested in seeing it implemented in code. But,
487 because one hacker coding in solitude fails to qualify as a free
488 software development effort, you need to ask yourself a second
489 question: <emphasis>Is anybody else interested?</emphasis>
493 Sometimes the answer is a simple <quote>no.</quote> If you want
494 to write a set of scripts to sort <emphasis>your</emphasis>
495 <acronym>MP3</acronym> collection on <emphasis>your</emphasis>
496 machine, <emphasis>maybe</emphasis> the free software development
497 model is not the best one to choose. However, if you want to
498 write a set of scripts to sort <emphasis>anyone's</emphasis>
499 <acronym>MP3</acronym>s, a free software project might fill a
504 Luckily, the Internet is a place so big and so diverse that,
505 chances are, there is someone, somewhere, who shares your
506 interests and who feels the same <quote>itch.</quote> It is the
507 fact that there are so many people with so many similar needs and
508 desires that introduces the third major question: <emphasis>Has
509 somebody already had your idea or a reasonably similar
514 <title>Finding Similar Projects</title>
517 There are places you can go on the web to try and answer the
518 question above. If you have experience with the free software
519 community, you are probably already familiar with many of these
520 sites. All of the resources listed below offer searching of
527 <term>freshmeat.net</term>
529 <para><ulink url="http://freshmeat.net">freshmeat.net</ulink>
530 describes itself as, <quote>the Web's largest index of Linux
531 and Open Source software</quote> and its reputation along
532 these lines is totally unparalleled and unquestioned. If you
533 can't find it on freshmeat, its doubtful that you (or anyone
534 else) will find it at all.</para>
539 <term>Slashdot</term>
541 <para><ulink url="http://slashdot.org">Slashdot</ulink>
542 provides <quote>News for Nerds. Stuff that matters,</quote>
543 which usually includes discussion of free software, open
544 source, technology, and geek culture news and events. It is
545 not unusual for a particularly sexy development effort to be
546 announced here, so it is definitely worth checking.</para>
551 <term>SourceForge</term>
553 <para><ulink url="http://sourceforge.net">SourceForge</ulink>
554 houses and facilitates a growing number of open source and
555 free software projects. It is also quickly becoming a nexus
556 and a necessary stop for free software
557 developers. SourceForge's <ulink
558 url="http://sourceforge.net/softwaremap/trove_list.php">software
559 map</ulink> and <ulink url="http://sourceforge.net/new/"> new
560 release</ulink> pages should be necessary stops before
561 embarking on a new free software project. SourceForge also
563 url="http://sourceforge.net/snippet/">Code Snippet
564 Library</ulink> which contains useful reusable chunks of code
565 in an array of languages which can come in useful in any
571 <term>Google and Google's Linux Search</term>
573 <para><ulink url="http://www.google.com">Google</ulink> and
574 <ulink url="http://www.google.com/linux"> Google's Linux
575 Search</ulink>, provides powerful web searches that may reveal
576 people working on similar projects. It is not a catalog of
577 software or news like freshmeat or Slashdot, but it is worth
578 checking to make sure you aren't pouring your effort into a
579 redundant project.</para>
588 <title>Deciding to Proceed</title>
590 Once you have successfully charted the terrain and have an idea
591 about what kinds of similar free software projects exist, every
592 developer needs to decide whether to proceed with their own
593 project. It is rare that a new project seeks to accomplish a
594 goal that is not at all similar or related to the goal of
595 another project. Anyone starting a new project needs to ask
596 themselves: <quote>Will the new project be duplicating work done
597 by another project? Will the new project be competing for
598 developers with an existing project? Can the goals of the new
599 project be accomplished by adding functionality to an existing
604 If the answer to any of these questions is <quote>yes,</quote>
605 try to contact the developer of the existing project(s) in
606 question and see if he or she might be willing to collaborate
611 For many developers this may be the single most difficult aspect
612 of free software project management, but it is an essential one. It is
613 easy to become fired up by an idea and get caught up in the
614 momentum and excitement of a new project. It is often extremely
615 difficult to do, but it is important that any free software
616 developer remembers that the best interests of the free software
617 community and the quickest way to accomplish your own project's
618 goals and the goals of similar projects can often be
619 accomplished by <emphasis>not</emphasis> starting a new
627 <!-- Section2: naming-->
630 <title>Naming your project</title>
633 While there are plenty of projects that fail with descriptive
634 names and plenty that succeed without them, I think naming your
635 project is worth giving a bit of thought. Leslie Orchard tackles
636 this issue in an <ulink
637 url="http://www.advogato.org/article/67.html">Advogato
638 article</ulink>. His article is short and definitely worth looking
643 The synopsis is that Orchard recommends you pick a name where,
644 after hearing the name, many users or developers will both:
650 <para>Know what the project does.</para>
653 <para>Remember it tomorrow.</para>
659 Humorously, Orchard's project, <quote>Iajitsu,</quote> does
660 neither. It is probably unrelated that development has effectively
661 frozen since the article was written.
665 He makes a good point though. There are companies whose only job
666 is to make names for pieces of software. They make
667 <emphasis>ridiculous</emphasis> amount of money doing it and are
668 supposedly worth it. While you probably can't afford a company like
669 this, you can afford to learn from their existence and think a
670 little bit about the name you are giving your project because it
671 <emphasis>does</emphasis> matter.
675 If there is a name you really want but it doesn't fit Orchard's
676 criteria, you can still go ahead. I thought <quote>gnubile</quote>
677 was one of the best I'd heard for a free software project ever and
678 I still talk about it long after I've stopped using the
679 program. However, if you can be flexible on the subject, listen to
680 Orchard's advice. It might help you.
684 <!-- Section2: licensing-->
686 <sect2 id="licensing">
687 <title>Licensing your Software</title>
690 On one (somewhat simplistic) level, the difference between a piece
691 of free software and a piece of propriety software is the
692 license. A license helps you as the developer by protecting your
693 legal rights to have your software distributed under your terms
694 and helps demonstrate to those who wish to help you or your
695 project that they are encouraged to join.
698 <sect3 id="chooselicense">
699 <title>Choosing a license</title>
702 Any discussion of licenses is also sure to generate at least a
703 small flame war as there are strong feelings that some free
704 software licenses are better than others. This discussion also
705 brings up the question of <quote>Open Source Software</quote> and
706 the debate over the terms <quote>Open Source Software</quote> and
707 <quote>Free Software</quote>. However, because I've written the
708 Free Software Project Management HOWTO and not the Open Source
709 Software Project Management HOWTO, my own allegiances in this
710 argument are in the open.
714 In attempting to reach a middle ground through diplomacy without
715 sacrificing my own philosophy, I will recommend picking any
716 license that conforms to the <ulink
717 url="http://www.debian.org/social_contract">Debian Free Software
718 Guidelines</ulink>. Originally compiled by the Debian project
719 under Bruce Perens, the <acronym>DFSG</acronym> forms the first
720 version of the <ulink
721 url="http://www.opensource.org/docs/definition_plain.html">Open
722 Source Definition.</ulink> Examples of free licenses given by the
723 <acronym>DFSG</acronym> are the <acronym>GPL</acronym>, the
724 <acronym>BSD</acronym>, and the Artistic License. As ESR mentions
725 in his his HOWTO<xref linkend="esrhowto">, don't write your own
726 license if at all possible. The three licenses I mention all have
727 long interpretive traditions. They are also definitely free
728 software (and can therefore be distributed as part of Debian and
729 in other places that permit the transfer of free software).
733 Conforming to the definition of free software offered by Richard
735 url="http://www.gnu.org/philosophy/free-sw.html"><quote>The Free
736 Software Definition</quote></ulink>, any of these licenses will
737 uphold, <quote>users' freedom to run, copy, distribute, study,
738 change and improve the software.</quote> There are plenty of
739 other licenses that also conform to the <acronym>DFSG</acronym>
740 but sticking with a more well-known license will offer the
741 advantage of immediate recognition and understanding. Many
742 people write three or four sentences in a COPYING file and assume
743 that they have written a free software license--as my long
744 experience with the debian-legal mailing professes, this is very
749 In attempting a more in-depth analysis, I agree with Karl Fogel's
750 description of licenses as falling into two groups: those that
751 are the <acronym>GPL</acronym> and those that are not the
752 <acronym>GPL</acronym>.
756 Personally, I license all my software under the
757 <acronym>GPL</acronym>. Created and protected by the Free
758 Software Foundation and the GNU Project, the
759 <acronym>GPL</acronym> is the license for the Linux kernel,
760 GNOME, Emacs, and the vast majority of GNU/Linux software. It's
761 the obvious choice but I also believe it is a good one. Any BSD
762 fanatic will urge you to remember that there is a viral aspect to
763 the <acronym>GPL</acronym> that prevents the mixture of
764 <acronym>GPL</acronym>'ed code with non-<acronym>GPL</acronym>'ed
765 code. To many people (myself included), this is a benefit, but to
766 some, it is a major drawback.
770 Many people write three or four sentences in a COPYING file and
771 assume that they have written a free software license--as my long
772 experience with the debian-legal mailing professes, this is very
773 often not the case. It may not protect you, it may not protect
774 your software, and it may make things very difficult for people
775 that want to use your software but who pay a lot of attention to
776 the subtle legal points of licenses. If you are passionate about
777 a home-brewed license, run it by either people at <ulink
778 url="http://www.opensource.org">OSI</ulink> or the <ulink
779 url="mailto:debian-devel@lists.debian.org">debian-legal mailing
780 list</ulink> first protect yourself from unanticipated
781 side-effects of your license.
785 The three major licenses can be found at the following locations:
791 <para><ulink url="http://www.gnu.org/copyleft/gpl.html">The GNU
792 General Public License</ulink></para>
795 <para><ulink url="http://www.debian.org/misc/bsd.license">The
796 BSD License</ulink></para>
800 url="http://language.perl.com/misc/Artistic.html">The Artistic
801 License</ulink></para>
807 <emphasis>In any case, please read through any license before
808 your release your software under it. As the primary developer,
809 you can't afford any license surprises.</emphasis>
813 <sect3 id="licensechoose">
814 <title>The mechanics of licensing</title>
817 The text of the <acronym>GPL</acronym> offers <ulink
818 url="http://www.gnu.org/copyleft/gpl.html#SEC4">a good
819 description of the mechanics of applying a license</ulink> to a
820 piece of software. My quick checklist for applying a license
828 <para>Make yourself or the FSF the copyright holder for the
829 work. In a few rare cases, you might want to make a sponsoring
830 organization (if it's big and powerful enough) the copyright
831 holder instead. Doing this is as simple as putting the name in
832 the blank when you modify the notice of copyright
833 below. Contrary to popular belief, you don't need to file with
834 any organization. The notice alone is enough to copyright your
839 <para>If at all possible, attach and distribute a full copy of
840 the license with the source and binary by including a separate
845 <para>At the top of each source file in your program, attach a
846 notice of copyright and include information on where the full
847 license can be found. The <acronym>GPL</acronym> recommends
848 that each file begin with:</para>
851 <emphasis>one line to give the program's name and an idea of what it does.</emphasis>
852 Copyright (C) yyyy name of author
854 This program is free software; you can redistribute it and/or
855 modify it under the terms of the GNU General Public License
856 as published by the Free Software Foundation; either version 2
857 of the License, or (at your option) any later version.
859 This program is distributed in the hope that it will be useful,
860 but WITHOUT ANY WARRANTY; without even the implied warranty of
861 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
862 GNU General Public License for more details.
864 You should have received a copy of the GNU General Public License
865 along with this program; if not, write to the Free Software
866 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
870 The <acronym>GPL</acronym> goes on to recommend attaching
871 information on methods for contacting you (the author) via
872 email or physical mail.
878 The <acronym>GPL</acronym> continues and suggests that if your
879 program runs in an interactive mode, you should write the
880 program to output a notice each time it enters interactive
881 mode that includes a message like this one that points to full
882 information about the programs license:
886 Gnomovision version 69, Copyright (C) year name of author
887 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
888 type `show w'. This is free software, and you are welcome
889 to redistribute it under certain conditions; type `show c'
895 <para>Finally, it might be helpful to include a
896 <quote>copyright disclaimer</quote> from an employer or a
897 school if you work as a programmer or if it seems like your
898 employer or school might be able to make an argument for
899 ownership of your code later on. These aren't often needed but
900 there are plenty of free software developers who have gotten
901 into trouble and wish they'd asked for one.</para>
908 <sect3 id="licensewarning">
909 <title>Final license warning</title>
912 Please, please, please, place your software under
913 <emphasis>some</emphasis> license. It may not seem important, and
914 to you it may not be, but licenses <emphasis>are</emphasis>
915 important. For a piece of software to be included in the Debian
916 GNU/Linux distribution, it must have a license that fits the
917 <ulink url="http://www.debian.org/social_contract">Debian Free
918 Software Guidelines</ulink>. If your software has no license, it
919 can not be distributed as a package in Debian until you
920 re-release it under a free license. Please save yourself and
921 others trouble by releasing the first version of your software
922 with a clear license.
929 <!-- Section2: chooseversioning-->
931 <sect2 id="chooseversioning">
932 <title>Choosing a Method of Version Numbering</title>
935 <emphasis>The most important thing about a system of version
936 numbering is that there is one.</emphasis> It may seem pedantic to
937 emphasize this point but you'd be surprised at the number of
938 scripts and small programs that pop up without any version number
943 <emphasis>The second most important thing about a system of
944 numbering is that the numbers always go up.</emphasis> Automatic
945 version tracking systems and people's sense of order in the
946 universe will fall apart if version numbers don't rise. It doesn't
947 <emphasis>really</emphasis> matter if 2.1 is a big jump and
948 2.0.005 is a small jump but it does matter that 2.1 is more recent
953 Follow these two simple rules and you will not go (too)
954 wrong. Beyond this, the most common technique seems to be the
955 <quote>major level,</quote> <quote>minor level,</quote>
956 <quote>patch level</quote> version numbering scheme. Whether you
957 are familiar with the name or not, you interact with it all the
958 time. The first number is the major number and it signifies major
959 changes or rewrites. The second number is the minor number and it
960 represents added or tweaked functionality on top of a largely
961 coherent structure. The third number is the patch number and it
962 usually will only refer to releases fixing bugs.
966 The widespread use of this scheme is why I know the nature and
967 relative degree in the differences between a 2.4.12 release of the
968 Linux kernel and a 2.4.11, 2.2.12, and 1.2.12 without knowing
969 anything about any of the releases.
973 You can bend or break these rules, and people do. But beware, if
974 you choose to, someone will get annoyed, assume you don't know,
975 and try and educate you, probably not nicely. I always follow this
976 method and I implore you to do so as well.
980 There are several version numbering systems that are well known,
981 useful, and that might be worth looking into before you release
987 <term>Linux kernel version numbering:</term>
989 <para>The Linux kernel uses a versioning system where any odd
990 minor version number refers to an development or testing release
991 and any even minor version number refers to a stable
992 version. Think about it for a second. Under this system, 2.1 and
993 2.3 kernels were and always will be development or testing
994 kernels and 2.0, 2.2. and 2.4 kernels are all production code
995 with a higher degree of stability and more testing.
999 Whether you plan on having a split development model (as
1000 described in <xref linkend="branches">) or only one version
1001 released at a time, my experience with several free software
1002 projects and with the Debian project has taught me that use of
1003 Linux's version numbering system is worth taking into
1004 consideration. In Debian, <emphasis>all</emphasis> minor
1005 versions are stable distributions (2.0, 2.1, etc). However,
1006 many people assume that 2.1 is an unstable or development
1007 version and continue to use an older version until they get so
1008 frustrated with the lack of development progress that they
1009 complain and figure the system out. If you never release an odd
1010 minor version but only release even ones, nobody is hurt, and
1011 less people are confused. It's an idea worth taking into
1018 <term>Wine version numbering:</term>
1020 <para>Because of the unusual nature of wine's development where
1021 the not-emulator is constantly improving but not working toward
1022 any immediately achievable goal, wine is released every three
1023 weeks. Wine does this by labeling their releases in <quote>Year
1024 Month Day</quote> format where each release might be labeled
1025 <quote>wine-XXXXXXXX</quote> where the version from January 04,
1026 2000 would be <quote>wine-20000104</quote>. For certain
1027 projects, <quote>Year Month Day</quote> format can make a lot of
1034 <term>Mozilla milestones:</term>
1036 <para>When one considers Netscape 6 and vendor versions, the
1037 mozilla's project development structure is one of the most
1038 complex free software models available. The project's version
1039 numbering has reflected the unique situation in which it is
1044 Mozilla's version numbering structure has historically been
1045 made up of milestones. From the beginning of the mozilla
1046 project, the goals of the project in the order and degree to
1047 which they were to be achieved were charted out on a series of
1048 <ulink url="http://www.mozilla.org/roadmap.html">road
1049 maps</ulink>. Major points and achievements along these
1050 road-maps were marked as milestones. Therefore, although
1051 Mozilla was built and distributed nightly as <quote>nightly
1052 builds,</quote> on a day when the goals of a milestone on the
1053 road-map had been reached, that particular build was marked as
1054 a <quote>milestone release.</quote>
1058 While I haven't seen this method employed in any other projects
1059 to date, I like the idea and think that it might have value in
1060 any testing or development branch of a large application under
1069 <!-- Section2: documentation-->
1071 <sect2 id="documentation">
1072 <title>Documentation</title>
1075 A huge number of otherwise fantastic free software applications
1076 have withered and died because their author was the only person
1077 who knew how to use them fully. Even if your program is written
1078 primarily for a techno-savvy group of users, documentation is
1079 helpful and even necessary for the survival of your project. You
1080 will learn later in <xref linkend="releasing"> that you should
1081 always release something that is usable. <emphasis>A piece of
1082 software without documentation is not usable.</emphasis>
1086 There are lots of different people you should document for and
1087 there are lots of ways to document your project. <emphasis>The
1088 importance of documentation in source code to help facilitate
1089 development by a large community is vital</emphasis> but it falls
1090 outside the scope of this HOWTO. This being the case, this section
1091 deals with useful tactics for user-directed documentation.
1095 A combination of tradition and necessity has resulted in a
1096 semi-regular system of documentation in most free software
1097 projects that is worth following. Both users and developers expect
1098 to be able to get documentation in several ways and it's essential
1099 that you provide the information they are seeking in a form they
1100 can read if your project is ever going to get off the
1101 ground. People have come to expect:
1105 <title>Man pages</title>
1107 <para>Your users will want to be able to type <quote>man
1108 yourprojectname</quote> end up with a nicely formatted man page
1109 highlighting the basic use of your application. Make sure that
1110 before you release your program, you've planned for this.
1114 Man pages are not difficult to write. There is excellent
1115 documentation on the man page writing process available through
1116 the <quote>The Linux Man-Page-HOWTO</quote> which is available
1117 through the Linux Documentation project <acronym>(LDP)</acronym>
1118 and is written by Jens Schweikhardt. It is available <ulink
1119 url="http://www.schweikhardt.net/man_page_howto.html">from
1120 Schweikhardt's site</ulink> or <ulink
1121 url="http://www.linuxdoc.org/HOWTO/mini/Man-Page.html">from the
1122 <acronym>LDP</acronym></ulink>.
1126 It is also possible to write man pages using DocBook
1127 SGML. Because man pages are so simple and the DocBook method
1128 relatively new, I have not been able to follow this up but would
1129 love help from anyone who can give me more information on how
1130 exactly how this is done.
1135 <title>Command line accessible documentation</title>
1138 Most users will expect some basic amount of documentation to be
1139 easily available from the command line. For few programs should
1140 this type of documentation extend for more than one screen (24 or
1141 25 lines) but it should cover the basic usage, a brief (one or
1142 two sentence) description of the program, a list of the commands
1143 with explanations, as well as all the major options (also with
1144 explanations), plus a pointer to more in-depth documentation for
1145 those who need it. The command line documentation for Debian's
1146 apt-get serves as an excellent example and a useful model:
1150 apt 0.3.19 for i386 compiled on May 12 2000 21:17:27
1151 Usage: apt-get [options] command
1152 apt-get [options] install pkg1 [pkg2 ...]
1154 apt-get is a simple command line interface for downloading and
1155 installing packages. The most frequently used commands are update
1159 update - Retrieve new lists of packages
1160 upgrade - Perform an upgrade
1161 install - Install new packages (pkg is libc6 not libc6.deb)
1162 remove - Remove packages
1163 source - Download source archives
1164 dist-upgrade - Distribution upgrade, see apt-get(8)
1165 dselect-upgrade - Follow dselect selections
1166 clean - Erase downloaded archive files
1167 autoclean - Erase old downloaded archive files
1168 check - Verify that there are no broken dependencies
1172 -q Loggable output - no progress indicator
1173 -qq No output except for errors
1174 -d Download only - do NOT install or unpack archives
1175 -s No-act. Perform ordering simulation
1176 -y Assume Yes to all queries and do not prompt
1177 -f Attempt to continue if the integrity check fails
1178 -m Attempt to continue if archives are unlocatable
1179 -u Show a list of upgraded packages as well
1180 -b Build the source package after fetching it
1181 -c=? Read this configuration file
1182 -o=? Set an arbitary configuration option, eg -o dir::cache=/tmp
1183 See the apt-get(8), sources.list(5) and apt.conf(5) manual
1184 pages for more information and options.
1188 It has become a GNU convention to make this type of information
1189 accessible with the <quote>-h</quote> and the
1190 <quote>--help</quote> options. Most GNU/Linux users will expect
1191 to be able to retrieve basic documentation these ways so if you
1192 choose to use different methods, be prepared for the flames and
1193 fallout that may result.
1198 <title>Files users will expect</title>
1200 In addition to man pages and command-line help, there are certain
1201 files where people will look for documentation, especially in any
1202 package containing source code. In a source distribution, most of
1203 these files can be stored in the root directory of the source
1204 distribution or in a subdirectory of the root called
1205 <quote>doc</quote> or <quote>Documentation.</quote> Common files
1206 in these places include:
1212 <term>README or Readme</term>
1215 <para>A document containing all the basic installation,
1216 compilation, and even basic use instructions that make up the
1217 bare minimum information needed to get the program up and
1218 running. A README is not your chance to be verbose but should
1219 be concise and effective. An ideal README is at least 30 lines
1220 long and more no more than 250.</para>
1225 <term>INSTALL or Install</term>
1228 <para>The INSTALL file should be much shorter than the README
1229 file and should quickly and concisely describe how to build
1230 and install the program. Usually an INSTALL file simply
1231 instructs the user to run <quote>./configure; make; make
1232 install</quote> and touches on any unusual options or actions
1233 that may be necessary. For most relatively standard install
1234 procedures and for most programs, INSTALL files are as short
1235 as possible and are rarely over 100 lines.</para>
1240 <term>CHANGELOG, Changelog, ChangeLog, or changelog</term>
1243 <para>A CHANGELOG is a simple file that every well-managed
1244 free software project should include. A CHANGELOG is simple
1245 the file that, as its name implies, logs or documents the
1246 changes you make to your program. The most simple way to
1247 maintain a CHANGELOG is to simply keep a file with the source
1248 code for your program and add a section to the top of the
1249 CHANGELOG with each release describing what has been changed,
1250 fixed, or added to the program. It's a good idea to post the
1251 CHANGELOG onto the website as well because it can help people
1252 decide whether they want or need to upgrade to a newer version
1253 or wait for a more significant improvement.</para>
1261 <para>A NEWS file and a ChangeLog are similar. Unlike a
1262 CHANGELOG, a NEWS file is not typically updated with new
1263 versions. Whenever new features are added, the developer
1264 responsible will make a note in the NEWS file. NEWS files
1265 should not have to be changed before a release (they should be
1266 kept up to date all along) but it's usually a good idea to
1267 check first anyway because often developers just forget to
1268 keep them as current as they should.</para>
1273 <term><acronym>FAQ</acronym></term>
1276 <para>For those of you that don't already know,
1277 <acronym>FAQ</acronym> stands for Frequently Asked Questions
1278 and a FAQ is a collection of exactly that. FAQs are not
1279 difficult to make. Simply make a policy that if you are asked
1280 a question or see a question on a mailing list two or more
1281 times, add the question (and its answer) to your FAQ. FAQs are
1282 more optional than the files listed above but they can save
1283 your time, increase usability, and decrease headaches on all
1293 <title>Website</title>
1295 It's only indirectly an issue of documentation but a good website
1296 is quickly becoming an essential part of any free software
1297 project. Your website should provide access to your documentation
1298 (in <acronym>HTML</acronym> if possible). It should also include
1299 a section for news and events around your program and a section
1300 that details the process of getting involved with development or
1301 testing and make an open invitation. It should also supply links
1302 to any mailing lists, similar websites, and provide a direct link
1303 to all the available ways of downloading your software.
1308 <title>Other documentation hints</title>
1313 All your documentation should be in plaintext, or, in cases
1314 where it is on your website primarily, in HTML. Everyone can
1315 cat a file, everyone has a pager, (almost) everyone can render
1316 HTML. <emphasis>You are welcome to distribute information in
1317 PDF, PostScript, RTF, or any number of other widely used
1318 formats but this information must also be available in
1319 plaintext or HTML or people will be very angry at
1320 you.</emphasis> In my opinion, info falls into this category
1321 as well. There is plenty of great GNU documentation that
1322 people simply don't read because it only in info. And this
1323 <emphasis>does</emphasis> make people angry. It's not a
1324 question of superior formats; it is a question of
1325 accessability and the status quo plays a huge role in this
1332 It doesn't hurt to distribute any documentation for your
1333 program from your website (FAQs etc) with your program. Don't
1334 hesitate to throw any of this in the program's tarball. If
1335 people don't need it, they will delete it. I can repeat it over
1336 and over: <emphasis>Too much documentation is not a
1342 <para>Unless your software is particular to a non-English
1343 language (a Japanese language editor for example), please
1344 distribute it with English language documentation. If you don't
1345 speak English or not not confident in your skills, ask a friend
1346 for help. Like it or not, fair or unfair, <emphasis>English is
1347 the language of free software</emphasis>. However, this does not
1348 mean you should limit your documentation to only English. If you
1349 speak another language, distribute translations of documentation
1350 with your software if you have the time and energy to do
1351 so. They will invariably be useful to someone.</para>
1356 Finally, <emphasis>please spell-check your
1357 documentation.</emphasis> Misspellings in documentation are
1358 bugs. I'm very guilty of committing this error and it's
1359 extremely easy to do. If English is not your first language,
1360 have a native speaker look over or edit your documentation or
1361 web pages. Poor spelling or grammar goes a long way to making
1362 your code look unprofessional. In code comments, this type of
1363 thing is less important but in man pages and web pages these
1364 mistakes are not acceptable.
1374 <!-- Section2: presentation -->
1376 <sect2 id="presentation">
1377 <title>Other Presentation Issues</title>
1379 Many of the remaining issues surrounding the creation of a new
1380 free software program fall under what most people describe as
1381 common sense issues. Its often said that software engineering is
1382 90 percent common sense combined with 10 percent specialized
1383 knowledge. Still, they are worth noting briefly in hopes that they
1384 may remind a developer of something they may have forgotten.
1388 <title>Package File Names</title>
1390 I agree with ESR when he says that: <quote> It's helpful to
1391 everybody if your archive files all have GNU-like names --
1392 all-lower-case alphanumeric stem prefix, followed by a dash,
1393 followed by a version number, extension, and other
1394 suffixes.</quote> There is more info (including lots of examples
1395 of what <emphasis>not</emphasis> to do in his <citetitle>Software
1396 Release Practices HOWTO</citetitle> which is included in this
1397 HOWTO's bibliography and can be found through the LDP.
1402 <title>Package formats</title>
1404 Package formats may differ depending on the system you are
1405 developing for. For windows based software, Zip archives (.zip)
1406 usually serve as the package format of choice. If you are
1407 developing for GNU/Linux, *BSD, or any UN*X, make sure that your
1408 source code is always available in tar'ed and gzip'ed format
1409 (.tar.gz). UNIX compress (.Z) has gone out of style and
1410 usefulness and faster computers have brought bzip2 (.bz2) into
1411 the spot-light as a more effective compression medium. I now make
1412 all my releases available in both gzip'ed and bzip2'ed tarballs.
1416 Binary packages should always be distribution specific. If you
1417 can build binary packages against a current version of a major
1418 distribution, you will only make your users happy. Try to foster
1419 relationships with users or developers of large distributions to
1420 develop a system for the consistent creation of binary
1421 packages. It's often a good idea to provide RedHat
1422 <acronym>RPM</acronym>'s (.rpm), Debian deb's (.deb) and source
1423 <acronym>RPM</acronym>'s <acronym>SRPM</acronym>'s if
1424 possible. Remember: <emphasis>While these binaries packages are
1425 nice, getting the source packaged and released should always be
1426 your priority. Your users or fellow developers can and will do
1427 the the binary packages for you.</emphasis>
1432 <title>Version control systems</title>
1435 A version control system can make a lot of these problems of
1436 packaging (and a lot of other problems mentioned in this HOWTO)
1437 less problematic. If you are using *NIX, CVS is your best bet. I
1438 recommend Karl Fogel's book on the subject (and the <ulink
1439 url="http://cvsbook.red-bean.com/">posted HTML version</ulink>)
1444 CVS or not, you should probably invest some time into learning
1445 about a version control system because it provides an automated
1446 way of solving many of the problems described by this HOWTO. I
1447 am not aware of any free version control systems for Windows or
1448 Mac OS but I know that CVS clients exist for both
1449 platforms. Websites like <ulink
1450 url="http://sourceforge.net">SourceForge</ulink> do a great job
1451 as well with a nice, easy-to-use web interface to CVS.
1455 I'd love to devote more space in this HOWTO to CVS because I love
1456 it (I even use CVS to keep versions straight on this HOWTO!) but
1457 I think it falls outside the scope of this document and already
1458 has its own HOWTOs. Most notably is the <citetitle>CVS Best
1459 Practices HOWTO</citetitle><xref linkend="cvsbestpractices">
1460 which I've included in the attached bibliography.
1466 <title>Useful tidbits and presentation hints</title>
1469 Other useful hints include:
1477 <emphasis>Make sure that your program can always be found in a
1478 single location.</emphasis> Often this means that you have a
1479 single directory accessible via <acronym>FTP</acronym> or the
1480 web where the newest version can be quickly recognized. One
1481 effective technique is a provide a symlink called
1482 <quote>yourprojectname-latest</quote> that is always pointing
1483 to the most recent released or development version of your
1484 free software application. Keep in mind that this location
1485 will receive many requests for downloads around releases so
1486 make sure that the server you choose has adequate bandwidth.
1492 <emphasis>Make sure that there is a consistent email address
1493 for bug reports.</emphasis> It's usually a good idea to make
1494 this something that is NOT your primary email address like
1495 yourprojectname@host or yourprojectname-bugs@host. This way,
1496 if you ever decide to hand over maintainership or if your
1497 email address changes, you simply need to change where this
1498 email address forwards. It also will allow for more than one
1499 person to deal with the influx of mail that is created if your
1500 project becomes as huge as you hope it will.
1510 <!-- Section1: starting: END -->
1512 <!-- Section1: developers -->
1514 <sect1 id="developers">
1515 <title>Maintaining a Project: Interacting with Developers</title>
1517 <primary>fswd!developers</primary>
1521 Once you have gotten your project started, you have overcome the
1522 most difficult hurdles in the development process of your
1523 program. Laying a firm foundation is essential, but the development
1524 process itself is equally important and provides just as many
1525 opportunities for failure. In the next two sections, I will
1526 describe running a project by discussing how to maintain a
1527 development effort through interactions with developers and with
1532 In releasing your program, your program becomes free software. This
1533 transition is more than just a larger user base. By releasing your
1534 program as free software, <emphasis>your</emphasis> software
1535 becomes the <emphasis>free software community's</emphasis>
1536 software. The direction of your software's development will be
1537 reshaped, redirected, and fully determined by your users and, to a
1538 larger extent, by other developers in the community.
1542 The major difference between free software development and
1543 propriety software development is the developer base. As the leader
1544 of a free software project, you need to attract and keep developers
1545 in a way that leaders of proprietary software projects simply don't
1546 have to worry about. <emphasis>As the person leading development of
1547 a free software project, you must harness the work of fellow
1548 developers by making responsible decisions and by responsibly
1549 choosing not to make decisions. You have to direct developers
1550 without being overbearing or bossy. You need to strive to earn
1551 respect and never forget to give it out.</emphasis>
1554 <!-- Section2: delegation -->
1556 <sect2 id="delegation">
1557 <title>Delegating Work</title>
1560 By now, you've hypothetically followed me through the early
1561 programming of a piece of software, the creation of a website and
1562 system of documentation, and we've gone ahead and (as will be
1563 discussed in <xref linkend="releasing">) released it to the rest
1564 of the world. Times passes, and if things go well, people become
1565 interested and want to help. The patches begin flowing in.
1569 <emphasis>Like the parent of any child who grows up, it's now time
1570 to wince, smile and do most difficult thing in any parents
1571 life: It's time to let go.</emphasis>
1575 Delegation is the political way of describing this process of
1576 <quote>letting go.</quote> It is the process of handing some of
1577 the responsibility and power over your project to other
1578 responsible and involved developers. It is difficult for anyone
1579 who has invested a large deal of time and energy into a project
1580 but it essential for the growth of any free software project. One
1581 person can only do so much. A free software project is nothing
1582 without the involvement of <emphasis>a group</emphasis> of
1583 developers. A group of developers can only be maintained through
1584 respectful and responsible leadership and delegation.
1588 As your project progresses, you will notice people who are putting
1589 significant amounts of time and effort into your project. These
1590 will be the people submitting the most patches, posting most on
1591 the mailing lists, and engaging in long email discussions. It is
1592 your responsibility to contact these people and to try and shift
1593 some of the power and responsibility of your position as the
1594 project's maintainer onto them (if they want it). There are
1595 several easy ways you can do this:
1599 In a bit of a disclaimer, delegation need not mean rule by
1600 committee. In many cases it does and this has been proven to
1601 work. In other cases this has created problems. <ulink
1602 url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
1603 Projects the Open Source Way</ulink> argues that <quote>OSS
1604 projects do best when one person is the clear leader of a team and
1605 makes the big decisions (design changes, release dates, and so
1606 on).</quote> I think this often true but would urge developers to
1607 consider the ideas that the project leader need not be the
1608 project's founder and that these important powers need not all rest
1609 with one person but that a release manager may be different than a
1610 lead developer. These situations are tricky politically so
1611 be careful and make sure it's necessary before you go around
1616 <title>How to delegate</title>
1619 You may find that other developers seem even more experienced or
1620 knowledgeable than you. Your job as a maintainer does not mean
1621 you have to be the best or the brightest. It means you
1622 are responsible for showing good judgment and for
1623 recognizing which solutions are maintainable and which are not.
1626 Like anything, its easier to watch others delegate than to do it
1627 yourself. In a sentence: <emphasis>Keep an eye out for other
1628 qualified developers who show an interest and sustained
1629 involvement with your project and try and shift responsibility
1630 toward them.</emphasis> The following ideas might be good places
1631 to start or good sources of inspiration:
1635 <title>Allow a larger group of people to have write access to your CVS
1636 repository and make real efforts toward rule by a
1640 <ulink url="http://httpd.apache.org/">Apache</ulink> is an
1641 example of a project that is run by small group of developers
1642 who vote on major technical issues and the admission of new
1643 members and all have write access to the main source
1644 repository. Their process is detailed <ulink
1645 url="http://httpd.apache.org/ABOUT_APACHE.html">online.</ulink>
1649 The <ulink url="http://www.debian.org/"> Debian Project</ulink>
1650 is an extreme example of rule by committee. At current count,
1651 more than 700 developers have full responsibility for
1652 aspects of the project. All these developers can upload into
1653 the main FTP server, and vote on major issues. Direction for
1654 the project is determined by the project's <ulink
1655 url="http://www.debian.org/social_contract">social
1656 contract</ulink> and a <ulink
1657 url="http://www.debian.org/devel/constitution">constitution</ulink>. To
1658 facilitate this system, there are special teams (i.e. the
1659 install team, the Japanese language team) as well as a technical
1660 committee and a project leader. The leader's main responsibility
1661 is to, <quote>appoint delegates or delegate decisions to the
1662 Technical Committee.</quote>
1666 While both of these projects operate on a scale that your
1667 project will not (at least initially), their example is
1668 helpful. Debian's idea of a project leader who can do
1669 <emphasis>nothing</emphasis> but delegate serves as a
1670 caricature of how a project can involve and empower a huge
1671 number of developers and grow to a huge size.
1676 <sect4 id="releasemanager">
1677 <title>Publicly appoint someone as the release manager for a
1678 specific release</title>
1681 A release manager is usually responsible for coordinating
1682 testing, enforcing a code freeze, being responsible for
1683 stability and quality control, packaging up the software, and
1684 placing it in the appropriate places to be downloaded.
1688 This use of the release manager is a good way to give yourself a
1689 break and to shift the responsibility for accepting and
1690 rejecting patches onto someone else. It is a good way of very
1691 clearly defining a chunk of work on the project as belonging to
1692 a certain person and its a great way of giving yourself room to
1697 <sect4 id="delegatebranch">
1698 <title>Delegate control of an entire branch</title>
1700 If your project chooses to have branches (as described in <xref
1701 linkend="branches">), it might be a good idea to appoint someone
1702 else to be the the head of a branch. If you like focusing your
1703 energy on development releases and the implementation of new
1704 features, hand total control over the stable releases to a
1705 well-suited developer.
1709 The author of Linux, Linus Torvalds, came out and crowned Alan
1710 Cox as <quote>the man for stable kernels.</quote> All patches
1711 for stable kernels go to Alan and, if Linus were to be taken
1712 away from work on Linux for any reason, Alan Cox would be more
1713 than suited to fill his role as the acknowledged heir to the
1714 Linux maintainership.
1720 <!-- Section2: patching -->
1722 <sect2 id="patching">
1723 <title>Accepting and Rejecting Patches</title>
1725 This HOWTO has already touched on the fact that as the maintainer
1726 of a free software project, one of your primary and most important
1727 responsibilities will be accepting and rejecting patches submitted
1728 to you by other developers.
1732 <title>Encouraging Good Patching</title>
1734 <para>As the person managing or maintaining the project, you
1735 aren't the person who is going to be making a lot of
1736 patches. However, it's worth knowing about ESR's section on
1737 <citetitle>Good Patching Practice</citetitle> in the
1738 <citetitle>Software Release Practices HOWTO</citetitle><xref
1739 linkend="esrhowto">. I don't agree with ESR's claim that most ugly
1740 or undocumented patches are probably worth throwing out at first
1741 sight--this just hasn't been my experience, especially when
1742 dealing with bug fixes that often don't come in the form of
1743 patches at all. Of course, this doesn't mean that I
1744 <emphasis>like</emphasis> getting poorly done patches. If you get
1745 ugly -e patches, if you get totally undocumented patches, and
1746 especially if they are anything more than trivial bug-fixes, it
1747 might be worth judging the patch by some of the criteria in ESR's
1748 HOWTO and then throwing people the link to the document so they
1749 can do it the <quote>right way.</quote>
1755 <title>Technical judgment</title>
1758 In <emphasis>Open Source Development with CVS</emphasis>, Karl
1759 Fogel makes a convincing argument that the most important things
1760 to keep in mind when rejecting or accepting patches are:
1767 <para>A firm knowledge of the scope of your program (that's the
1768 <quote>idea</quote> I talked about in <xref linkend="chooseproject">);</para>
1772 <para>The ability to recognize, facilitate, and direct
1773 <quote>evolution</quote> of your program so that the program
1774 can grow and change and incorporate functionality that was
1775 originally unforeseen;</para>
1779 <para>The necessity to avoid digressions that might expand the
1780 scope of the program too much and result and push the project
1781 toward an early death under its own weight and
1782 unwieldiness.</para>
1789 These are the criteria that you as a project maintainer should
1790 take into account each time you receive a patch.
1794 Fogel elaborates on this and states the <quote>the
1795 questions to ask yourself when considering whether to implement
1796 (or approve) a change are:</quote>
1803 <para>Will it benefit a significant percentage of the program's
1804 user community?</para>
1808 <para>Does it fit within the program's domain or within a
1809 natural, intuitive extension of that domain?</para>
1816 The answers to these questions are never straightforward and its
1817 very possible (and even likely) that the person who submitted the
1818 patch may feel differently about the answer to these questions
1819 than you do. However, if you feel that that the answer to either
1820 of those questions is <quote>no,</quote> it is your responsibility
1821 to reject the change. If you fail to do this, the project will
1822 become unwieldy and unmaintainable and many ultimately fail.
1827 <title>Rejecting patches</title>
1830 Rejecting patches is probably the most difficult and sensitive
1831 job that the maintainer of any free software project has to
1832 face. But sometimes it has to be done. I mentioned earlier (in
1833 <xref linkend="developers"> and in <xref linkend="delegation">)
1834 that you need to try and balance your responsibility and power to
1835 make what you think are the best technical decisions with the
1836 fact that you will lose support from other developers if you seem
1837 like you are on a power trip or being overly bossy or possessive
1838 of the community's project. I recommend that you keep these three
1839 major concepts in mind when rejecting patches (or other changes):
1843 <title>Bring it to the community</title>
1845 One of the best ways of justifying a decision to reject a patch
1846 and working to not seem like you keep an iron grip on your
1847 project is by not making the decision alone at all. It might
1848 make sense to turn over larger proposed changes or more
1849 difficult decisions to a development mailing list where they can
1850 be discussed and debated. There will be some patches (bug fixes,
1851 etc.) which will definitely be accepted and some that you feel
1852 are so off base that they do not even merit further
1853 discussion. It is those that fall into the gray area between
1854 these two groups that might merit a quick forward to a mailing
1859 I recommend this process wholeheartedly. As the project
1860 maintainer you are worried about making the best decision for
1861 the project, for the project's users and developers, and for
1862 yourself as a responsible project leader. Turning things over to
1863 an email list will demonstrate your own responsibility and
1864 responsive leadership as it tests and serves the interests of
1865 your software's community.
1870 <title>Technical issues are not always good justification</title>
1872 Especially toward the beginning of your project's life, you
1873 will find that many changes are difficult to implement,
1874 introduce new bugs, or have other technical problems. Try to see
1875 past these. Especially with added functionality, good ideas do
1876 not always come from good programmers. Technical merit is a
1877 valid reason to postpone an application of a patch but it is not
1878 always a good reason to reject a change outright. Even small
1879 changes are worth the effort of working with the developer
1880 submitting the patch to iron out bugs and incorporate the change
1881 if you think it seems like a good addition to your project. The
1882 effort on your part will work to make your project a community
1883 project and it will pull a new or less experienced developer
1884 into your project and even teach them something that might help
1885 them in making their next patch.
1890 <title>Common courtesy</title>
1892 It should go without saying but, <emphasis>above all and in all
1893 cases, just be nice.</emphasis> If someone has an idea and cares
1894 about it enough to write some code and submit a patch, they
1895 care, they are motivated, and they are already involved. Your
1896 goal as the maintainer is make sure they submit again. They may
1897 have thrown you a dud this time but next time may be the idea or
1898 feature that revolutionizes your project.
1902 It is your responsibility to first justify your choice to not
1903 incorporate their change clearly and concisely. Then thank
1904 them. Let them know that you a appreciate their help and feel
1905 horrible that you can't incorporate their change. Let them know
1906 that you look forward to their staying involved and you hope
1907 that the next patch or idea meshes better with your project
1908 because you appreciate their work and want to see it in your
1909 application. If you have ever had a patch rejected after putting
1910 a large deal of time, thought, and energy into it, you remember
1911 how it feels and it feels bad. Keep this in mind when you have
1912 to let someone down. It's never easy but you need to do
1913 everything you can to make it as not-unpleasant as possible.
1919 <!-- Section2: branches -->
1921 <sect2 id="branches">
1922 <title>Stable and Development Branches</title>
1925 The idea of stable and development branches has already been
1926 described briefly in <xref linkend="chooseversioning"> and in
1927 <xref linkend="delegatebranch">. These allusions attest to some of
1928 the ways that multiple branches can affect your software. Branches
1929 can let you avoid (to some extent) some of the problems around
1930 rejecting patches (as described in <xref linkend="patching">) by
1931 allowing you to temporarily compromise the stability of your
1932 project without affecting those users who need that stability.
1936 The most common way of branching your project is to have one
1937 branch that is stable and one that is for development. This is the
1938 model followed by the Linux kernel that is described in <xref
1939 linkend="chooseversioning">. In this model, there is
1940 <emphasis>always</emphasis> one branch that is stable and always
1941 one that is in development. Before any new release, the
1942 development branch goes into a <quote>feature freeze</quote> as
1943 described in <xref linkend="freezing"> where major changes and
1944 added features are rejected or put on hold under the development
1945 kernel is released as the new stable branch and major development
1946 resumes on the development branch. Bug fixes and small changes
1947 that are unlikely to have any large negative repercussions are
1948 incorporated into the stable branch as well as the development
1953 Linux's model provides an extreme example. On many projects, there is no
1954 need to have two versions constantly available. It may make sense to
1955 have two versions only near a release. The Debian project has
1956 historically made both a stable and an unstable distribution
1957 available but has expanded to this to include: stable, unstable,
1958 testing, experimental, and (around release time) a frozen
1959 distribution that only incorporates bug fixes during the
1960 transition from unstable to stable. There are few projects whose
1961 size would necessitate a system like Debian's but this use of
1962 branches helps demonstrate how they can be used to balance
1963 consistent and effective development with the need to make regular
1964 and usable releases.
1968 In trying to set up a development tree for yourself, there are
1969 several things that might be useful to keep in mind:
1976 <term>Minimize the number of branches</term>
1978 <para>Debian may be able to make good use of four or five
1979 branches but it contains gigabytes of software in over 5000
1980 packages compiled for 5-6 different architectures. For you,
1981 two is probably a good ceiling. Too many branches will confuse
1982 your users (I can't count how many times I had to describe
1983 Debian's system when it only had 2 and sometimes 3 branches!),
1984 potential developers and even yourself. Branches can help but
1985 they come at a cost so use them very sparingly.</para>
1990 <term>Make sure that all your different branches are explained</term>
1992 <para>As I mentioned in the preceding paragraph, different
1993 branches <emphasis>will</emphasis> confuse your users. Do
1994 everything you can to avoid this by clearly explaining the
1995 different branches in a prominent page on your website and in a
1996 README file in the <acronym>FTP</acronym> or
1997 web directory.</para>
2000 I might also recommend against a mistake that I think Debian
2001 has made. The terms <quote>unstable,</quote>
2002 <quote>testing,</quote> and <quote>experimental</quote> are
2003 vague and difficult to rank in order of stability (or
2004 instability as the case may be). Try explaining to someone
2005 that <quote>stable</quote> actually means <quote>ultra
2006 stable</quote> and that <quote>unstable</quote> doesn't
2007 actually include any unstable software but is really stable
2008 software that is untested as a distribution.
2012 If you are going to use branches, especially early on, keep in
2013 mind that people are conditioned to understand the terms
2014 <quote>stable</quote> and <quote>development</quote> and you
2015 probably can't go wrong with this simple and common division of
2022 <term>Make sure all your branches are always available</term>
2024 <para>Like a lot of this document, this should probably should
2025 go without saying but experience has taught me that it's not
2026 always obvious to people. It's a good idea to physically split
2027 up different branches into different directories or directory
2028 trees on your <acronym>FTP</acronym> or web site. Linux
2029 accomplishes this by having kernels in a v2.2 and a v2.3
2030 subdirectory where it is immediately obvious (after you know
2031 their version numbering scheme) which directory is for the most
2032 recent stable and the current development releases. Debian
2033 accomplishes this by naming all their distribution with names
2034 (i.e. woody, potato, etc.) and then changing symlinks named
2035 <quote>stable,</quote> <quote>unstable</quote> and
2036 <quote>frozen</quote> to point to which ever distribution (by
2037 name) is in whatever stage. Both methods work and there are
2038 others. In any case, it is important that different branches
2039 are always available, are accessible from consistent locations,
2040 and that different branches are clearly distinguished from each
2041 other so your users know exactly what they want and where to
2051 <!-- Section2: otherdev -->
2053 <sect2 id="otherdev">
2054 <title>Other Project Management issues</title>
2056 There are more issues surrounding interaction with developers in a
2057 free software project that I can not touch on in great detail in a
2058 HOWTO of this size and scope. Please don't hesitate to contact me if you see
2059 any major omissions.
2063 Other smaller issues that are worth mentioning are:
2066 <sect3 id="freezing">
2067 <title>Freezing</title>
2069 For those projects that choose to adopt a split development model
2070 (<xref linkend="branches">), freezing is a concept that is worth
2071 becoming familiar with.
2075 Freezes come in two major forms. A <quote>feature freeze</quote>
2076 is a period when no significant functionality is added to a
2077 program. It is a period where established functionality (even
2078 skeletons of barely working functionality) can be improved and
2079 perfected. It is a period where bugs are fixed. This type of
2080 freeze is usually applied some period (a month or two) before a
2081 release. It is easy to push a release back as you wait for
2082 <quote>one more feature</quote> and a freeze helps to avoid this
2083 situation by drawing the much needed line in the sand. It gives
2084 developers room they need to get a program ready for release.
2088 The second type of freeze is a <quote>code freeze</quote> which
2089 is much more like a released piece of software. Once a piece of
2090 software has entered a <quote>code freeze,</quote> all changes to
2091 the code are discouraged and only changes that fix known bugs
2092 are permitted. This type of freeze usually follows a
2093 <quote>feature freeze</quote> and directly precedes a
2094 release. Most released software is in what could be interpreted
2095 as a sort of high level <quote>code freeze.</quote>
2099 Even if you never choose to appoint a release manager (<xref
2100 linkend="releasemanager">), you will have an easier time
2101 justifying the rejection or postponement of patches (<xref
2102 linkend="patching">) before a release with a publicly stated
2109 <title>Forks</title>
2111 I wasn't sure about how I would deal with forking in this
2112 document (or if I would deal with forking at all). A fork is when
2113 a group of developers takes code from a free software project and
2114 actually starts a brand new free software project with it. The
2115 most famous example of a fork was between Emacs and XEmacs. Both
2116 emacsen are based on an identical code-base but for technical,
2117 political, and philosophical reasons, development was split into
2118 two projects which now compete with each other.
2122 The short version of the fork section is, <emphasis>don't do
2123 them.</emphasis> Forks force developers to choose one project to
2124 work with, cause nasty political divisions, and redundancy of
2125 work. Luckily, usually the threat of the fork is enough to scare
2126 the maintainer or maintainers of a project into changing the way
2127 they run their project.
2131 In his chapter on <quote>The Open Source Process,</quote> Karl
2132 Fogel describes how to do a fork if you absolutely must. If you
2133 have determined that is absolutely necessary and that the
2134 differences between you and the people threatening to fork are
2135 absolutely unresolvable, I recommend Fogel's book as a good place
2141 <!-- Section1: users -->
2144 <title>Maintaining a Project: Interacting with Users</title>
2146 <primary>fswd!users</primary>
2150 If you've worked your way up to here, congratulations, you are
2151 nearing the end of this document. This final section describes some
2152 of the situations in which you, in your capacity as project
2153 maintainer, will be interacting with users. It gives some
2154 suggestions on how these situations might be handled effectively.
2158 Interacting with users is difficult. In our discussion of
2159 interaction with developers, the underlying assumption is that in a
2160 free software project, a project maintainer must constantly strive to
2161 attract and keep developers who can easily leave at any time.
2165 Users in the free software community are different than developers
2166 and are also different than users in the world of proprietary
2167 software and they should be treated differently than either
2168 group. Some ways in which the groups differ significantly follow:
2175 <para>The lines between users and developers are blurred in ways
2176 that is totally foreign to any proprietary development
2177 model. Your users are often your developers and vice
2182 <para>In the free software world, you are often your users' only
2183 choice. Because there is such an emphasis on not replicating the
2184 work of others in the free software community and because the
2185 element of competition present in the propriety software model is
2186 absent (or at least in an extremely different form) in the free
2187 software development model, you will probably be the only project
2188 that does what you do (or at least the only one that does what
2189 you do in the way that you do it). This means your responsiveness
2190 to your users is even more important than in the proprietary
2191 software world.</para>
2195 <para>In an almost paradoxical situation, free software projects
2196 have less immediate or dire consequences for ignoring their users
2197 altogether. It is also often easier to do. Because you don't
2198 usually need to compete with another product, chances are good
2199 that you will not be scrambling to gain the features of your
2200 competitor's newest program. This means that your development
2201 process will have to be directed either internally, by a
2202 commitment to your users, or through both.</para>
2208 Trying to tackle this unique situation can only be done
2209 indirectly. Developers and maintainers need to listen to users and
2210 to try and be as responsive as possible. A solid knowledge of the
2211 situation recounted above is any free software developer's best tool
2212 for shifting his development or leadership style to fit the unique
2213 process of free software project management. This chapters will try and
2214 introduce some of the more difficult or important points in any
2215 projects interactions with users and give some hints on how to
2219 <!-- Section2: testing -->
2221 <sect2 id="testing">
2222 <title>Testing and Testers</title>
2225 In addition to your users being your developers, they are also
2226 (and perhaps more commonly) your testers. Before I get flamed, I
2227 should rephrase my sentence: <emphasis>some of your
2228 users</emphasis> (those who explicitly volunteer) are your
2233 It is important that this distinction be made early on because not
2234 all of your users want to be testers. Many users want to use
2235 stable software and don't care if they don't have the newest,
2236 greatest software with the latest, greatest features. These users
2237 except a stable, tested piece of software without major or obvious
2238 bugs and will be angry if they find themselves testing. This is
2239 yet another way in which a split development model (as mentioned
2240 in <xref linkend="branches">) might come in handy.
2245 url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
2246 Projects the Open Source Way</ulink></quote> describes what a
2247 good test should look for:
2252 <term>Boundary conditions</term>
2255 <para>Maximum buffer lengths, data conversions, upper/lower
2256 boundary limits, and so on.</para>
2261 <term>Inappropriate behavior</term>
2264 <para>Its a good idea to find out what a program will do if a
2265 user hands it a value it isn't expecting, hits the wrong button,
2266 etc. Ask yourself a bunch of <quote>what if</quote> questions
2267 and think of anything that <emphasis>might</emphasis> fail or
2268 <emphasis>might</emphasis> go wrong and find out what your
2269 program would do in those cases.</para>
2274 <term>Graceful failure</term>
2277 <para>The answer to a number of the <quote>what if</quote>
2278 questions above is probably <quote>failure</quote> which is
2279 often the only answer. Now make sure that it happens
2280 nicely. Make sure that when it crashes, there is some indication
2281 of why it crashed or failed so that the user or developer
2282 understands whats going on.</para>
2288 <term>Standards conformance</term>
2291 <para>If possible, make sure your programs conforms to
2292 standards. If it's interactive, don't be too creative with
2293 interfaces. If it is non-interactive, make sure it communicates
2294 over appropriate and established channels with other programs
2295 and with the rest of the system.</para>
2302 <title>Automated testing</title>
2304 For many programs, many common mistakes can be caught by
2305 automated means. Automated tests tend to be pretty good at
2306 catching errors that you've run into several times before or
2307 the things you just forget. They are not very good at finding
2308 errors, even major ones, that are totally unforeseen.
2312 CVS comes with a Bourne shell script called sanity.sh that is
2313 worth looking at. Debian uses a program called lintian that
2314 checks Debian packages for all of the most common errors. While
2315 use of these scripts may not be helpful, there is a host of other
2316 sanity checking software on the net that may be applicable (feel
2317 free to email me any recommendations). None of these will create
2318 a bug-free release but they will avoid at least some major
2319 oversights. Finally, if your programs become a long term
2320 endeavor, you will find that there are certain errors that you
2321 tend to make over and over. Start a collection of scripts that
2322 check for these errors to help keep them out of future releases.
2327 <title>Testing by testers</title>
2329 For any program that depends on user interactivity, many bugs
2330 will only be uncovered through testing by users actually clicking
2331 the keys and pressing the mouse buttons. For this you need
2332 testers and as many as possible.
2336 The most difficult part of testing is finding testers. It's
2337 usually a good tactic to post a message to a relevant mailing
2338 list or news group announcing a specific proposed release date
2339 and outlining the functionality of your program. If you put some
2340 time into the announcement, you are sure to get a few responses.
2344 The second most difficult part of testing is
2345 <emphasis>keeping</emphasis> your testers and keeping them
2346 actively involved in the testing process. Fortunately, there are
2347 some tried and true tactics that can applied toward this end:
2354 <term>Make things simple for your testers</term>
2356 <para>Your testers are doing you a favor so make it as easy as
2357 possible for them. This means that you should be careful to
2358 package your software in a way that is easy to find, unpack,
2359 install, and uninstall. This also means you should explain
2360 what you are looking for to each tester and make the means for
2361 reporting bugs simple and well established. The key is to
2362 provide as much structure as possible to make your testers'
2363 jobs easy and to maintain as much flexibility as possible for
2364 those that want to do things a little differently.</para>
2369 <term>Be responsive to your testers</term>
2371 <para>When your testers submit bugs, respond to them and
2372 respond quickly. Even if you are only responding to tell them
2373 that the bug has already been fixed, quick and consistent
2374 responses make them feel like their work is heard, important,
2375 and appreciated.</para>
2380 <term>Thank your testers</term>
2382 <para>Thank them personally each time they send you
2383 patch. Thank them publicly in the documentation and the about
2384 section of your program. You appreciate your testers and your
2385 program would not be possible without their help. Make sure
2386 they know it. Publicly, pat them on the back to make sure the rest of
2387 the world knows it too. It will be appreciated more than you
2398 <!-- Section2: support -->
2400 <sect2 id="support">
2401 <title>Setting up Support Infrastructure</title>
2404 While testing is important, the large part of your interactions
2405 and responsibility to your users falls under the category of
2406 support. The best way to make sure your users are adequately
2407 supported in using your program is to set up a good infrastructure
2408 for this purpose so that your developers and users help each other
2409 and less of the burden falls on you. This way, people will also
2410 get quicker and better responses to their questions. This
2411 infrastructure comes in several major forms:
2415 <title>Documentation</title>
2417 It should not come as any surprise that the key element to any
2418 support infrastructure is good documentation. This topic was
2419 largely covered in <xref linkend="documentation"> and will not be
2424 <sect3 id="mailinglists">
2425 <title>Mailing lists</title>
2427 Aside from documentation, effective mailing lists will be your
2428 greatest tool in providing user support. Running a mailing list
2429 well is more complicated than installing mailing list software
2434 <title>Separate lists</title>
2437 A good idea is too separate your user and development mailing
2438 lists (perhaps into project-user@host and project-devel@host)
2439 and enforce the division. If people post a development question
2440 onto -user, politely ask them to repost it onto -devel and vise
2441 versa. Subscribe yourself to both groups and encourage all
2442 primarily developers to do the same.
2446 This system provides so that no one person is stuck doing all of
2447 the support work and works so that users learn more about the
2448 program, they can help newer users with their questions.
2453 <title>Choose mailing list software well</title>
2455 Please don't make the selection of mailing list software
2456 impulsively. Please consider easy accessibility by users without
2457 a lot of technical experience so you want to be as easy as
2458 possible. Web accessibility to an archive of the list is also
2463 The two biggest free software mailing list programs are <ulink
2464 url="http://www.greatcircle.com/majordomo/">majordomo</ulink>
2465 and <ulink url="http://www.list.org/">GNU Mailman</ulink>. A
2466 long time advocate of majordomo, I would now recommend any
2467 project choose GNU Mailman. It fulfills the criteria listed
2468 above and makes it easier. It provides a good mailing
2469 list program for a free software project maintainer as opposed
2470 to a good mailing list application for a mailing list
2475 There are other things you want to take into consideration in
2476 setting up your list. If it is possible to gate your mailing
2477 lists to Usenet and provide it in digest form as well as
2478 making them accessible on the web, you will please some users
2479 and work to make the support infrastructure slightly more
2486 <title>Other support ideas</title>
2489 A mailing list and accessible documentation are far from all you
2490 can do to set up good user support infrastructure. Be
2491 creative. If you stumble across something that works well, email me
2492 and I'll include it here.
2496 <title>Make your self accessible</title>
2498 You can not list too few methods to reach you. If you hang out
2499 in an <acronym>IRC</acronym> channel, don't hesitate to list it
2500 in your projects documentation. List email and snailmail
2501 addresses, and ways to reach you via <acronym>ICQ</acronym>,
2502 <acronym>AIM</acronym>, or Jabber if they apply.
2507 <title>Bug management software</title>
2509 For many large software projects, use of bug management software
2510 is essential to keep track of which bugs have been fixed, which
2511 bugs have not been fixed, and which bugs are being fixed by
2512 which people. Debian uses the <ulink
2513 url="http://bugs.debian.org">Debian Bug Tracking System</ulink>
2514 (<acronym>BTS</acronym>) although it may not be best choice for
2515 every project (it seems to currently be buckling under its own
2516 weight) As well as a damn good web browser, the Mozilla project
2517 has spawned a sub-project resulting in a bug tracking system
2519 url="http://www.mozilla.org/projects/bugzilla/">bugzilla</ulink>
2520 which has become extremely possible and which I like a lot.
2524 These systems (and others like them) can be unwieldy so
2525 developers should be careful to not spend more time on the bug
2526 tracking system than on the bugs or the projects themselves. If
2527 a project continues to grow, use of a bug tracking system can
2528 provide an easy standard avenue for users and testers to report
2529 bugs and for developers and maintainers to fix them and track
2530 them in an orderly fashion.
2536 <!-- Section2: releasing -->
2538 <sect2 id="releasing">
2539 <title>Releasing Your Program</title>
2542 As mentioned earlier in the HOWTO, the first rule of releasing is,
2543 <emphasis>release something useful.</emphasis> Non-working or
2544 not-useful software will not attract anyone to your
2545 project. People will be turned off of your project and will be likely
2546 to simply gloss over it next time they see a new version
2547 announced. Half-working software, if useful, will intrigue people,
2548 whet their appetites for versions to come, and encourage them to
2549 join the development process.
2553 <title>When to release</title>
2556 Making the decision to release your software for the first time
2557 is an incredibly important and incredibly stressful decision. But
2558 it needs to done. My advice is to try and make something that
2559 is complete enough to be usable and incomplete enough to allow
2560 for flexibility and room for imagination by your future
2561 developers. It's not an easy decision. Ask for help on a local
2562 Linux User Group mailing list or from a group of developer
2567 One tactic is to first do an <quote>alpha</quote> or
2568 <quote>beta</quote> release as described below in <xref
2569 linkend="alphabeta">. However, most of the guidelines described
2574 <emphasis>When you feel in your gut that it is time and you feel
2575 you've weighed the situation well several times, cross your
2576 fingers and take the plunge.</emphasis>
2580 After you've released for the first time, knowing when to release
2581 becomes less stressful, but just as difficult to gauge. I like
2582 the criteria offered by Robert Krawitz in his article, <ulink
2583 url="http://www.advogato.org/article/196.html"><quote>Free
2584 Software Project Management</quote></ulink> for maintaining a
2585 good release cycle. He recommends that you ask yourself,
2586 <quote>does this release...</quote>
2592 <para>Contain sufficient new functionality or bug fixes to be
2593 worth the effort.</para>
2597 <para>Be spaced sufficiently far apart to allow the user time
2598 to work with the latest release.</para>
2602 <para>Be sufficiently functional so that the user can get work
2603 done (quality).</para>
2609 If the answer is yes to all of these questions, its probably time
2610 for a release. If in doubt, remember that asking for advice can't
2616 <title>How to release</title>
2619 If you've followed the guidelines described in this HOWTO up
2620 until this point, the mechanics of doing a release are going to
2621 be the easy part of releasing. If you have set up consistent
2622 distribution locations and the other infrastructure described in
2623 the preceding sections, releasing should be as simple as building
2624 the package, checking it once over, and uploading it into the
2625 appropriate place and then making your website reflect the
2630 <sect3 id="alphabeta">
2631 <title>Alpha, beta, and development releases</title>
2634 When contemplating releases, it worth considering the fact that
2635 not every release needs to be a full numbered release. Software
2636 users are accustomed to pre-releases but you must be careful to
2637 label these releases accurately or they will cause more problems then
2642 The observation is often made that many free software developers
2643 seem to be confused about the release cycle. <quote><ulink
2644 url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
2645 Projects the Open Source Way</ulink></quote> suggests that you memorize
2646 the phrase, <quote>Alpha is not Beta. Beta is not Release</quote>
2647 and I'd agree that tis is a probably a good idea.
2654 <term>alpha releases</term>
2656 <para>Alpha software is feature-complete but sometimes only
2657 partially functional.</para>
2659 <para>Alpha releases are expected to be unstable, perhaps a
2660 little unsafe, but definitely usable. They
2661 <emphasis>can</emphasis> have known bugs and kinks that have
2662 yet to be worked out. Before releasing an alpha, be sure to
2663 keep in mind that <emphasis>alpha releases are still
2664 releases</emphasis> and people are not going to be expecting a
2665 nightly build from the CVS source. An alpha should work and
2666 have minimal testing and bug fixing already finished.</para>
2671 <term>beta releases</term>
2673 <para>Beta software is feature-complete and functional, but is
2674 in the testing cycle and still has a few bugs left to be
2677 <para>Beta releases are general expected to be usable and
2678 slightly unstable, although definitely <emphasis>not
2679 unsafe.</emphasis> Beta releases usually preclude a full
2680 release by under a month. They can contain small known bugs
2681 but no major ones. All major functionality should be fully
2682 implemented although the exact mechanics can still be worked
2683 out. Beta releases are great tool to whet the appetites of
2684 potential users by giving them a very realistic view of where
2685 your project is going to be in the very near future and can
2686 help keep interest by giving people
2687 <emphasis>something.</emphasis></para>
2692 <term>development releases</term>
2694 <para><quote>Development release</quote> is much a more vague
2695 term than <quote>alpha</quote> or <quote>beta</quote>. I
2696 usually choose to reserve the term for discussion of a
2697 development branch although there are other ways to use the
2698 term. So many in fact, that I feel the term has been
2699 cheapened. The popular window manager <ulink
2700 url="http://www.enlightenment.org">Enlightenment</ulink> has
2701 released <emphasis>nothing but</emphasis> development
2702 releases. Most often, the term is used to describe releases
2703 that are not even alpha or beta and if I were to release a
2704 pre-alpha version of a piece of software in order to keep
2705 interest in my project alive, this is probably how I would
2706 have to label it.</para>
2716 <!-- Section2: announcing -->
2718 <sect2 id="announcing">
2719 <title>Announcing Your Project</title>
2722 Well, you've done it. You've (at least for the purposes of this
2723 HOWTO) designed, built, and released your free software
2724 project. All that is left is for you to tell the world so they
2725 know to come and try it out and hopefully jump on board with
2726 development. If everything is in order as described above, this
2727 will be a quick and painless process. A quick announcement is all
2728 that it takes to put yourself on the free software community's
2733 <title>Mailing lists and Usenet</title>
2735 <para>Announce your software on Usenet's <ulink
2736 url="news:comp.os.linux.announce">comp.os.linux.announce</ulink>. If
2737 you only announce your software in two places, have it be c.o.l.a
2738 and freshmeat.</para>
2741 However, email is still the way that most people on the Internet
2742 get their information. Its a good idea to send a message
2743 announcing your program to any relevant mailing list you know of
2744 and any other relevant Usenet discussion groups.</para>
2746 <para>Karl Fogel recommends that use you simple subject
2747 describing the fact that the message is an announcement, the name
2748 of the program, the version, and a half-line long description of
2749 its functionality. This way, any interested user or developer
2750 will be immediately attracted to your announcement. Fogel's
2754 <screen>Subject: ANN: aub 1.0, a program to assemble Usenet binaries</screen>
2757 The rest of the email should describe the programs functionality
2758 quickly and concisely in no more than two paragraphs and should
2759 provide links to the projects webpage and direct links to
2760 downloads for those that want to try it right away. This form
2761 will work for both Usenet and mailing list posts.
2765 You should repeat this announcement process consistently in the
2766 same locations for each subsequent release.
2771 <title>freshmeat.net</title>
2773 Mentioned earlier in <xref linkend="evalwhere">, in today's free
2774 software community, announcements of your project on freshmeat
2775 are almost more important than announcements on mailing lists.
2779 Visit the <ulink url="http://freshmeat.net">freshmeat.net
2780 website</ulink> or their <ulink
2781 url="http://freshmeat.net/add-project/">submit project
2782 page</ulink> to post your project onto their site and into their
2783 database. In addition to a large website, freshmeat provides a
2784 daily newsletter that highlights all the days releases and
2785 reaches a huge audience (I personally skim it every night for any
2786 interesting new releases).
2791 <title>Project Mailing List</title>
2793 <para>If you've gone ahead and created mailing lists for your
2794 project, you should always announce new versions on these
2795 lists. I've found that for many projects, users request a very
2796 low-volume announce only mailing list to be notified when new
2797 versions are released. freshmeat.net now allows users to subscribe
2798 to a particular project so they receive emails every time a new
2799 version is announced through their system. It's free and it can
2800 stand in for an announce-only mailing list. In my opinion, it
2809 <title>Printed Books</title>
2814 <surname>Fogel</surname>
2815 <firstname>Karl</firstname>
2818 <title>Open Source Development with CVS</title>
2821 <publishername>Coriolois Open Press</publishername>
2823 <pubdate>1999</pubdate>
2825 <isbn>1-57610-490-7</isbn>
2829 Fogel's <quote>guide to using CVS in the free software
2830 world</quote> is much more than its subtitle. In the publisher's
2831 own words: <quote><emphasis>Open Source Development with
2832 CVS</emphasis> is one of the first books available that teaches
2833 you development and implementation of Open Source
2834 software.</quote> It also includes the best reference and
2835 tutorial to CVS I have ever seen. It is the book that was
2836 <emphasis>so good</emphasis> that it prompted me to write this
2837 HOWTO because I thought the role it tried to serve was so
2838 important and useful. Please check it or buy it if you can and
2839 are seriously interested in running a free software project.
2842 <para>In May of 2003, the entire book under the GPL. You can
2843 find the full text of the book <ulink
2844 url="http://cvsbook.red-bean.com/">here</ulink>.</para>
2852 <surname>Lessig</surname>
2853 <firstname>Lawrence</firstname>
2856 <title>Code and Other Laws of Cyberspace</title>
2859 <publishername>Basic Books</publishername>
2861 <pubdate>2000</pubdate>
2863 <isbn>0-465-03913-8</isbn>
2867 While it only briefly talks about free software (and does it by
2868 tiptoeing around the free software/open source issue with the
2869 spineless use of the term <quote>open code</quote> that only a
2870 lawyer could coin), Lessig's book is brilliant. Written by a
2871 lawyer, it talks about how regulation on the Internet is not
2872 done with law, but with the code itself and how the nature of
2873 the code will determine the nature of future freedoms. In
2874 addition to being a quick and enjoyable read, it gives some
2875 cool history and describes how we <emphasis>need</emphasis>
2876 free software in a way more powerfully than anything I've read
2878 url="http://www.gnu.org/philosophy/right-to-read.html">RMS's
2879 <quote>Right to Read.</quote></ulink>
2888 <surname>Raymond</surname>
2889 <firstname>Eric</firstname>
2892 <title>The Cathedral and the Bazaar</title>
2893 <subtitle>Musings on Linux and Open Source by an Accidental Revolutionary</subtitle>
2896 <publishername>O'Reilly</publishername>
2898 <pubdate>1999</pubdate>
2900 <isbn>1-56592-724-9</isbn>
2903 Although I have to honestly say that I am not the ESR fan that
2904 I used to be, this book proved invaluable in getting me where I
2905 am today. The essay that gives the book its title does a good
2906 job of sketching the free software process and does an an
2907 amazing job of making an argument for free software/open source
2908 development as a road to better software. The rest of the book
2909 has other of ESR's articles, which for the most part are posted
2910 on his website. Still, it's nice thing to own in hard copy and
2911 something that every free software/open source hacker should
2920 <title>Web-Accessible Resources</title>
2923 This is a list of the web resources pertaining to this HOWTO that
2924 I've found most helpful in compiling this information. If you know
2925 of others that would help, please don't hesitate to email me at
2926 <email>mako@atdot.cc</email> and we can look into getting it
2927 added to the list and represented in the HOWTO.
2931 I'd recommend that any free software developer (or potential one)
2932 skim through these sites because they have each have a lot to say.
2939 <surname>Dafermos</surname>
2940 <firstname>George</firstname>
2941 <othername>N</othername>
2944 <title><ulink url="http://firstmonday.org/issues/issue6_11/dafermos/">Management and Virtual Decentralized Networks: The Linux Project</ulink></title>
2947 <para>Since the paper includes its own abstract, I thought I
2948 would include it here verbatim:</para>
2950 <para><blockquote><para>This paper examines the latest of
2951 paradigms - the Virtual Network(ed) Organisation - and whether
2952 geographically dispersed knowledge workers can virtually
2953 collaborate for a project under no central
2954 planning. Co-ordination, management and the role of knowledge
2955 arise as the central areas of focus. The Linux Project and its
2956 development model are selected as a case of analysis and the
2957 critical success factors of this organisational design are
2958 identified. The study proceeds to the formulation of a
2959 framework that can be applied to all kinds of virtual
2960 decentralised work and concludes that value creation is
2961 maximized when there is intense interaction and uninhibited
2962 sharing of information between the organisation and the
2963 surrounding community. Therefore, the potential success or
2964 failure of this organisational paradigm depends on the degree
2965 of dedication and involvement by the surrounding
2966 community.</para></blockquote></para>
2968 <para>This paper was referred to me in my capacity as author of
2969 this HOWTO and I was very impressed. It's written by a graduate
2970 student in management and I think it succeeds at evaluating the
2971 Linux project as an example of a new paradigm in management--one
2972 that <emphasis>you</emphasis> will be be placing yourself at the
2973 center of in your capacity as maintainer of a free software
2976 <para>As a developer trying to control an application and guide
2977 it to success in the free software world, I'm not sure how
2978 useful Dafermos's argument is. It does however, provide a
2979 theoretical justification for my HOWTO--free software project
2980 management <emphasis>is</emphasis> a different creature than
2981 proprietary software project management. If you are interested
2982 in the conceptual and theoretical ways that free software
2983 project management differs from other types of management, this
2984 is a great paper to read. If this paper answers questions of
2985 <quote>how?</quote>, Dafermos answers the (more difficult to
2986 defend) questions of <quote>why?</quote> and does a very good
2997 <surname>Gabriel</surname>
2998 <firstname>Richard</firstname>
3002 url="http://www.jwz.org/doc/worse-is-better.html">The Rise of
3003 <quote>Worse is Better</quote></ulink></title>
3007 A well written article although I think the title may have
3008 confused as many people as the rest of the essay helped. It
3009 offers a good description of how to design programs that will
3010 succeed and stay maintainable as they grow.
3019 <surname>Manley</surname>
3020 <firstname>Montey</firstname>
3024 url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
3025 Projects the Open Source Way</ulink></title>
3028 <publishername><ulink
3029 url="http://www.linuxprogramming.com">Linux
3030 Programming</ulink></publishername>
3032 <pubdate>Oct 31, 2000</pubdate>
3036 In one of the better articles on the subject that I've read,
3037 Monty sums up some of the major points I touch on including:
3038 starting a project, testing, documentation, organizing a team and
3039 leadership, and several other topics. While more opinionated that
3040 I try to be, I think its an important article that I found very
3041 helpful in writing this HOWTO. I've tried to cite him in
3042 the places where I borrowed from him most.
3046 I have problems much of this piece and I recommend you read
3047 <xref linkend="krawitz"> at the same time you read Monty's
3048 article for a good critique.
3054 <biblioentry id="esrhowto">
3057 <surname>Raymond</surname>
3058 <firstname>Eric</firstname>
3059 <othername>Steven</othername>
3062 <title><ulink url="http://www.tldp.org/HOWTO/Software-Release-Practice-HOWTO/index.html">Software Release Practice HOWTO</ulink></title>
3066 <para>At first glance, ESR's release practice HOWTO seems to
3067 share a lot of terrain with this document. Upon closer
3068 examination, the differences become apparent but they are
3069 closely related. His document, read in conjunction with mine,
3070 will give a reader a good picture of how to go about managing a
3071 project. ESR's HOWTO goes into a bit more detail on how to write
3072 and what languages to write in. He tends to give more specific
3073 instructions and checklists (<quote>name this file this, not
3074 this</quote>) while this HOWTO speaks more conceptually. There
3075 are several sections that are extremely similar. It's also
3076 <emphasis>much</emphasis> shorter.</para>
3078 <para>My favorite quote from his HOWTO is: <quote>"Managing a
3079 project well when all the participants are volunteers presents
3080 some unique challenges. This is too large a topic to cover in a
3081 HOWTO.</quote> Oh really? Perhaps I just do a poor job.</para>
3088 <biblioentry id="cvsbestpractices">
3091 <surname>Venugopalan</surname>
3092 <firstname>Vivek</firstname>
3095 <title><ulink url="http://www.magic-cauldron.com/cm/cvs-bestpractices/index.html">CVS Best Practices</ulink></title>
3099 <para>Venugopalan provides one of the best essays on
3100 effective use of CVS that I've come across. It is written for
3101 people who already have a good knowledge of CVS. In the chapter
3102 on branching, he describes when and how to branch but gives no
3103 information on what CVS commands you should use to do this. This
3104 is fine (technical CVS HOWTO have been written) but CVS newbies
3105 will want to spend some time with Fogel's reference before they
3106 will find this one very useful.</para>
3108 <para>Venugopalan creates checklists of things to do before,
3109 after, and around releases. It's definitely worth a read through
3110 as most of his ideas will save tons of developer head aches over
3111 any longer period of time.</para>
3120 <title>Advogato Articles</title>
3123 I've found that one of the best resources that any free software
3124 developer has at his or her disposal is Advogato.org. If you haven't
3125 yet had a chance to visit <ulink url="http://www.advogato.org">the
3126 website</ulink>, do.
3130 I have spent a huge amount of time on Advogato and I've gone
3131 through and provided links to the articles that I think might be
3132 of particular interest to anyone reading this HOWTO. I think that
3133 skimming through these links can be helpful and I promise that if
3134 you do, you'll learn a lot. You will learn that my idea of how a
3135 free software project should be run is not the
3136 <emphasis>only</emphasis> idea. I think that's important.
3140 If nothing else, there is <emphasis>way</emphasis> more
3141 information on that website than I could ever fit into, or
3142 reference from this HOWTO. I have listed what I think are the most
3143 relevant articles here with short descriptions that I've written.
3150 <surname>Hindle</surname>
3151 <firstname>Stephen</firstname>
3154 <title><ulink url="http://www.advogato.org/article/262.html">'Best Practices' for Open Source?</ulink></title>
3157 <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
3159 <pubdate>March 21, 2001</pubdate>
3163 Touching mostly on programming practice (as most articles on
3164 the subject usually do), the article talks a little about
3165 project management (<quote>Use it!</quote>) and a bit about
3166 communication within a free software project.
3175 <surname>Cohen</surname>
3176 <firstname>Bram</firstname>
3180 url="http://www.advogato.org/article/258.html"></ulink>How to
3181 Write Maintainable Code</title>
3184 <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
3186 <pubdate>March 15, 2001</pubdate>
3190 This article touches upon the "writing maintainable code"
3191 discussion that I try hard to avoid in my HOWTO. It's one of
3192 the better (and most diplomatic) articles on the subject that
3198 <biblioentry id="krawitz">
3201 <surname>Krawitz</surname>
3202 <firstname>Robert</firstname>
3205 <title><ulink url="http://www.advogato.org/article/196.html">Free
3206 Source Project Management</ulink></title>
3209 <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
3211 <pubdate>November 4, 2000</pubdate>
3215 This article made me happy because it challenged many of the
3216 problems that I had with Monty's article on <ulink
3217 url="http://www.linuxprogramming.com">LinuxProgramming</ulink>. The
3218 author argues that Monty calls simply for the application of
3219 old (proprietary software) project management techniques in
3220 free software projects instead of working to come up with
3221 something new. I found his article to be extremely well thought
3222 out and I think it's an essential read for any free software
3232 <surname>Martins</surname>
3233 <firstname>Lalo</firstname>
3236 <title><ulink url="http://www.advogato.org/article/128.html">Ask
3237 the Advogatos: why do Free Software projects
3238 fail?</ulink></title>
3241 <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
3243 <pubdate>July 20, 2000</pubdate>
3247 While the article is little more than a question, reading the
3248 answers to this question offered by Advogato's readers can
3249 help. In a lot of ways, this HOWTO acts as my answer to the
3250 questions posed in this article but there are others, many of
3251 which might take issue with whats is in this HOWTO. It's worth
3261 <surname>Burley</surname>
3262 <firstname>David</firstname>
3266 url="http://www.advogato.org/article/107.html">In-Roads to Free
3267 Software Development</ulink></title>
3270 <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
3272 <pubdate>June 14, 2000</pubdate>
3276 This document was written as a response to <ulink
3277 url="http://www.advogato.org/article/72.html">another Advogato
3278 article</ulink>. Although not about running a project, this
3279 describes some of the ways that you can get started with free
3280 software development without starting a project. I think this
3281 is an important article. If you are interested in becoming
3282 involved with free software, this article showcases some of the
3283 ways that you can do this without actually starting a project
3284 (something that I hope this HOWTO has demonstrated is not to be
3294 <surname>Moorman</surname>
3295 <firstname>Jacob</firstname>
3298 <title><ulink url="http://www.advogato.org/article/72.html">Importance of
3299 Non-Developer Supporters in Free Software</ulink><title></title>
3302 <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
3304 <pubdate>April 16, 2000</pubdate>
3308 Moorman's is a short article but it brings up some good
3309 points. The comment reminding developers to thank their testers
3310 and end-users is invaluable and oft-forgotten.
3319 <surname>Orchard</surname>
3320 <firstname>Leslie</firstname>
3323 <title><ulink url="http://www.advogato.org/article/67.html">On
3324 Naming an Open Source Project</ulink></title>
3327 <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
3329 <pubdate>April 12, 2000</pubdate>
3333 I didn't even have a section on project naming in this HOWTO
3334 (See <xref linkend="naming">) until Leslie Orchard's article
3335 reminded me of it. Thanks to Leslie for writing this article!
3344 <surname>Allen</surname>
3345 <firstname>David</firstname>
3348 <title><ulink url="http://www.advogato.org/article/40.html">Version Numbering Madness</ulink></title>
3351 <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
3353 <pubdate>February 28, 2000</pubdate>
3357 In this article, David Allen challenges the whole
3358 <quote>Major.Minor.Patch</quote> version numbering scheme. Its
3359 good to read this as you read <xref
3360 linkend="chooseversioning">. I liked the article and it
3361 describes some of the projects that I bring up in my discussion
3362 of version numbering.
3372 The GNU Free Documentation License 1.1 in DocBook
3373 Markup by Eric Baudais <baudais@okstate.edu>
3374 Maintained by the GNOME Documentation Project
3375 http://developer.gnome.org/projects/gdp
3377 Last Modified: Nov 16, 2000
3383 Version 1.1, March 2000
3386 <year>2000</year><holder>Free Software Foundation, Inc.</holder>
3388 <legalnotice id="fdl-legalnotice">
3390 <address>Free Software Foundation, Inc. <street>59 Temple Place,
3391 Suite 330</street>, <city>Boston</city>, <state>MA</state>
3392 <postcode>02111-1307</postcode> <country>USA</country></address>
3393 Everyone is permitted to copy and distribute verbatim copies of this
3394 license document, but changing it is not allowed.
3398 <title>GNU Free Documentation License</title>
3400 <simplesect id="fdl-preamble">
3401 <title>0. PREAMBLE</title>
3403 The purpose of this License is to make a manual, textbook, or
3404 other written document <quote>free</quote> in the sense of
3405 freedom: to assure everyone the effective freedom to copy and
3406 redistribute it, with or without modifying it, either
3407 commercially or non-commercially. Secondarily, this License
3408 preserves for the author and publisher a way to get credit for
3409 their work, while not being considered responsible for
3410 modifications made by others.
3414 This License is a kind of <quote>copyleft</quote>, which means
3415 that derivative works of the document must themselves be free in
3416 the same sense. It complements the GNU General Public License,
3417 which is a copyleft license designed for free software.
3421 We have designed this License in order to use it for manuals for
3422 free software, because free software needs free documentation: a
3423 free program should come with manuals providing the same
3424 freedoms that the software does. But this License is not limited
3425 to software manuals; it can be used for any textual work,
3426 regardless of subject matter or whether it is published as a
3427 printed book. We recommend this License principally for works
3428 whose purpose is instruction or reference.
3431 <simplesect id="fdl-simplesect1">
3432 <title>1. APPLICABILITY AND DEFINITIONS</title>
3433 <para id="fdl-document">
3434 This License applies to any manual or other work that contains a
3435 notice placed by the copyright holder saying it can be
3436 distributed under the terms of this License. The
3437 <quote>Document</quote>, below, refers to any such manual or
3438 work. Any member of the public is a licensee, and is addressed
3439 as <quote>you</quote>.
3442 <para id="fdl-modified">
3443 A <quote>Modified Version</quote> of the Document means any work
3444 containing the Document or a portion of it, either copied
3445 verbatim, or with modifications and/or translated into another
3449 <para id="fdl-secondary">
3450 A <quote>Secondary Section</quote> is a named appendix or a
3451 front-matter section of the <link
3452 linkend="fdl-document">Document</link> that deals exclusively
3453 with the relationship of the publishers or authors of the
3454 Document to the Document's overall subject (or to related
3455 matters) and contains nothing that could fall directly within
3456 that overall subject. (For example, if the Document is in part a
3457 textbook of mathematics, a Secondary Section may not explain any
3458 mathematics.) The relationship could be a matter of historical
3459 connection with the subject or with related matters, or of
3460 legal, commercial, philosophical, ethical or political position
3464 <para id="fdl-invariant">
3465 The <quote>Invariant Sections</quote> are certain <link
3466 linkend="fdl-secondary"> Secondary Sections</link> whose titles
3467 are designated, as being those of Invariant Sections, in the
3468 notice that says that the <link
3469 linkend="fdl-document">Document</link> is released under this
3473 <para id="fdl-cover-texts">
3474 The <quote>Cover Texts</quote> are certain short passages of
3475 text that are listed, as Front-Cover Texts or Back-Cover Texts,
3476 in the notice that says that the <link
3477 linkend="fdl-document">Document</link> is released under this
3481 <para id="fdl-transparent">
3482 A <quote>Transparent</quote> copy of the <link
3483 linkend="fdl-document"> Document</link> means a machine-readable
3484 copy, represented in a format whose specification is available
3485 to the general public, whose contents can be viewed and edited
3486 directly and straightforwardly with generic text editors or (for
3487 images composed of pixels) generic paint programs or (for
3488 drawings) some widely available drawing editor, and that is
3489 suitable for input to text formatters or for automatic
3490 translation to a variety of formats suitable for input to text
3491 formatters. A copy made in an otherwise Transparent file format
3492 whose markup has been designed to thwart or discourage
3493 subsequent modification by readers is not Transparent. A copy
3494 that is not <quote>Transparent</quote> is called
3495 <quote>Opaque</quote>.
3499 Examples of suitable formats for Transparent copies include
3500 plain ASCII without markup, Texinfo input format, LaTeX input
3501 format, SGML or XML using a publicly available DTD, and
3502 standard-conforming simple HTML designed for human
3503 modification. Opaque formats include PostScript, PDF,
3504 proprietary formats that can be read and edited only by
3505 proprietary word processors, SGML or XML for which the DTD
3506 and/or processing tools are not generally available, and the
3507 machine-generated HTML produced by some word processors for
3508 output purposes only.
3511 <para id="fdl-title-page">
3512 The <quote>Title Page</quote> means, for a printed book, the
3513 title page itself, plus such following pages as are needed to
3514 hold, legibly, the material this License requires to appear in
3515 the title page. For works in formats which do not have any title
3516 page as such, <quote>Title Page</quote> means the text near the
3517 most prominent appearance of the work's title, preceding the
3518 beginning of the body of the text.
3522 <simplesect id="fdl-section2">
3523 <title>2. VERBATIM COPYING</title>
3525 You may copy and distribute the <link
3526 linkend="fdl-document">Document</link> in any medium, either
3527 commercially or non-commercially, provided that this License, the
3528 copyright notices, and the license notice saying this License
3529 applies to the Document are reproduced in all copies, and that
3530 you add no other conditions whatsoever to those of this
3531 License. You may not use technical measures to obstruct or
3532 control the reading or further copying of the copies you make or
3533 distribute. However, you may accept compensation in exchange for
3534 copies. If you distribute a large enough number of copies you
3535 must also follow the conditions in <link
3536 linkend="fdl-section3">section 3</link>.
3540 You may also lend copies, under the same conditions stated
3541 above, and you may publicly display copies.
3545 <simplesect id="fdl-section3">
3546 <title>3. COPYING IN QUANTITY</title>
3548 If you publish printed copies of the <link
3549 linkend="fdl-document">Document</link> numbering more than 100,
3550 and the Document's license notice requires <link
3551 linkend="fdl-cover-texts">Cover Texts</link>, you must enclose
3552 the copies in covers that carry, clearly and legibly, all these
3553 Cover Texts: Front-Cover Texts on the front cover, and
3554 Back-Cover Texts on the back cover. Both covers must also
3555 clearly and legibly identify you as the publisher of these
3556 copies. The front cover must present the full title with all
3557 words of the title equally prominent and visible. You may add
3558 other material on the covers in addition. Copying with changes
3559 limited to the covers, as long as they preserve the title of the
3560 <link linkend="fdl-document">Document</link> and satisfy these
3561 conditions, can be treated as verbatim copying in other
3566 If the required texts for either cover are too voluminous to fit
3567 legibly, you should put the first ones listed (as many as fit
3568 reasonably) on the actual cover, and continue the rest onto
3573 If you publish or distribute <link
3574 linkend="fdl-transparent">Opaque</link> copies of the <link
3575 linkend="fdl-document">Document</link> numbering more than 100,
3576 you must either include a machine-readable <link
3577 linkend="fdl-transparent">Transparent</link> copy along with
3578 each Opaque copy, or state in or with each Opaque copy a
3579 publicly-accessible computer-network location containing a
3580 complete Transparent copy of the Document, free of added
3581 material, which the general network-using public has access to
3582 download anonymously at no charge using public-standard network
3583 protocols. If you use the latter option, you must take
3584 reasonably prudent steps, when you begin distribution of Opaque
3585 copies in quantity, to ensure that this Transparent copy will
3586 remain thus accessible at the stated location until at least one
3587 year after the last time you distribute an Opaque copy (directly
3588 or through your agents or retailers) of that edition to the
3593 It is requested, but not required, that you contact the authors
3594 of the <link linkend="fdl-document">Document</link> well before
3595 redistributing any large number of copies, to give them a chance
3596 to provide you with an updated version of the Document.
3600 <simplesect id="fdl-section4">
3601 <title>4. MODIFICATIONS</title>
3603 You may copy and distribute a <link
3604 linkend="fdl-modified">Modified Version</link> of the <link
3605 linkend="fdl-document">Document</link> under the conditions of
3606 sections <link linkend="fdl-section2">2</link> and <link
3607 linkend="fdl-section3">3</link> above, provided that you release
3608 the Modified Version under precisely this License, with the
3609 Modified Version filling the role of the Document, thus
3610 licensing distribution and modification of the Modified Version
3611 to whoever possesses a copy of it. In addition, you must do
3612 these things in the Modified Version:
3615 <itemizedlist mark="opencircle">
3620 Use in the <link linkend="fdl-title-page">Title
3621 Page</link> (and on the covers, if any) a title distinct
3622 from that of the <link
3623 linkend="fdl-document">Document</link>, and from those of
3624 previous versions (which should, if there were any, be
3625 listed in the History section of the Document). You may
3626 use the same title as a previous version if the original
3627 publisher of that version gives permission.
3636 List on the <link linkend="fdl-title-page">Title
3637 Page</link>, as authors, one or more persons or entities
3638 responsible for authorship of the modifications in the
3639 <link linkend="fdl-modified">Modified Version</link>,
3640 together with at least five of the principal authors of
3641 the <link linkend="fdl-document">Document</link> (all of
3642 its principal authors, if it has less than five).
3651 State on the <link linkend="fdl-title-page">Title
3652 Page</link> the name of the publisher of the <link
3653 linkend="fdl-modified">Modified Version</link>, as the
3663 Preserve all the copyright notices of the <link
3664 linkend="fdl-document">Document</link>.
3673 Add an appropriate copyright notice for your modifications
3674 adjacent to the other copyright notices.
3683 Include, immediately after the copyright notices, a
3684 license notice giving the public permission to use the
3685 <link linkend="fdl-modified">Modified Version</link> under
3686 the terms of this License, in the form shown in the
3696 Preserve in that license notice the full lists of <link
3697 linkend="fdl-invariant"> Invariant Sections</link> and
3698 required <link linkend="fdl-cover-texts">Cover
3699 Texts</link> given in the <link
3700 linkend="fdl-document">Document's</link> license notice.
3709 Include an unaltered copy of this License.
3718 Preserve the section entitled <quote>History</quote>, and
3719 its title, and add to it an item stating at least the
3720 title, year, new authors, and publisher of the <link
3721 linkend="fdl-modified">Modified Version </link>as given on
3722 the <link linkend="fdl-title-page">Title Page</link>. If
3723 there is no section entitled <quote>History</quote> in the
3724 <link linkend="fdl-document">Document</link>, create one
3725 stating the title, year, authors, and publisher of the
3726 Document as given on its Title Page, then add an item
3727 describing the Modified Version as stated in the previous
3737 Preserve the network location, if any, given in the <link
3738 linkend="fdl-document">Document</link> for public access
3739 to a <link linkend="fdl-transparent">Transparent</link>
3740 copy of the Document, and likewise the network locations
3741 given in the Document for previous versions it was based
3742 on. These may be placed in the <quote>History</quote>
3743 section. You may omit a network location for a work that
3744 was published at least four years before the Document
3745 itself, or if the original publisher of the version it
3746 refers to gives permission.
3755 In any section entitled <quote>Acknowledgements</quote> or
3756 <quote>Dedications</quote>, preserve the section's title,
3757 and preserve in the section all the substance and tone of
3758 each of the contributor acknowledgements and/or
3759 dedications given therein.
3768 Preserve all the <link linkend="fdl-invariant">Invariant
3769 Sections</link> of the <link
3770 linkend="fdl-document">Document</link>, unaltered in their
3771 text and in their titles. Section numbers or the
3772 equivalent are not considered part of the section titles.
3781 Delete any section entitled
3782 <quote>Endorsements</quote>. Such a section may not be
3783 included in the <link linkend="fdl-modified">Modified
3793 Do not retitle any existing section as
3794 <quote>Endorsements</quote> or to conflict in title with
3795 any <link linkend="fdl-invariant">Invariant
3803 If the <link linkend="fdl-modified">Modified Version</link>
3804 includes new front-matter sections or appendices that qualify as
3805 <link linkend="fdl-secondary">Secondary Sections</link> and
3806 contain no material copied from the Document, you may at your
3807 option designate some or all of these sections as invariant. To
3808 do this, add their titles to the list of <link
3809 linkend="fdl-invariant">Invariant Sections</link> in the
3810 Modified Version's license notice. These titles must be
3811 distinct from any other section titles.
3815 You may add a section entitled <quote>Endorsements</quote>,
3816 provided it contains nothing but endorsements of your <link
3817 linkend="fdl-modified">Modified Version</link> by various
3818 parties--for example, statements of peer review or that the text
3819 has been approved by an organization as the authoritative
3820 definition of a standard.
3824 You may add a passage of up to five words as a <link
3825 linkend="fdl-cover-texts">Front-Cover Text</link>, and a passage
3826 of up to 25 words as a <link
3827 linkend="fdl-cover-texts">Back-Cover Text</link>, to the end of
3828 the list of <link linkend="fdl-cover-texts">Cover Texts</link>
3829 in the <link linkend="fdl-modified">Modified Version</link>.
3830 Only one passage of Front-Cover Text and one of Back-Cover Text
3831 may be added by (or through arrangements made by) any one
3832 entity. If the <link linkend="fdl-document">Document</link>
3833 already includes a cover text for the same cover, previously
3834 added by you or by arrangement made by the same entity you are
3835 acting on behalf of, you may not add another; but you may
3836 replace the old one, on explicit permission from the previous
3837 publisher that added the old one.
3841 The author(s) and publisher(s) of the <link
3842 linkend="fdl-document">Document</link> do not by this License
3843 give permission to use their names for publicity for or to
3844 assert or imply endorsement of any <link
3845 linkend="fdl-modified">Modified Version </link>.
3849 <simplesect id="fdl-section5">
3850 <title>5. COMBINING DOCUMENTS</title>
3852 You may combine the <link linkend="fdl-document">Document</link>
3853 with other documents released under this License, under the
3854 terms defined in <link linkend="fdl-section4">section 4</link>
3855 above for modified versions, provided that you include in the
3856 combination all of the <link linkend="fdl-invariant">Invariant
3857 Sections</link> of all of the original documents, unmodified,
3858 and list them all as Invariant Sections of your combined work in
3863 The combined work need only contain one copy of this License,
3864 and multiple identical <link linkend="fdl-invariant">Invariant
3865 Sections</link> may be replaced with a single copy. If there are
3866 multiple Invariant Sections with the same name but different
3867 contents, make the title of each such section unique by adding
3868 at the end of it, in parentheses, the name of the original
3869 author or publisher of that section if known, or else a unique
3870 number. Make the same adjustment to the section titles in the
3871 list of Invariant Sections in the license notice of the combined
3876 In the combination, you must combine any sections entitled
3877 <quote>History</quote> in the various original documents,
3878 forming one section entitled <quote>History</quote>; likewise
3879 combine any sections entitled <quote>Acknowledgements</quote>,
3880 and any sections entitled <quote>Dedications</quote>. You must
3881 delete all sections entitled <quote>Endorsements.</quote>
3885 <simplesect id="fdl-section6">
3886 <title>6. COLLECTIONS OF DOCUMENTS</title>
3888 You may make a collection consisting of the <link
3889 linkend="fdl-document">Document</link> and other documents
3890 released under this License, and replace the individual copies
3891 of this License in the various documents with a single copy that
3892 is included in the collection, provided that you follow the
3893 rules of this License for verbatim copying of each of the
3894 documents in all other respects.
3898 You may extract a single document from such a collection, and
3899 dispbibute it individually under this License, provided you
3900 insert a copy of this License into the extracted document, and
3901 follow this License in all other respects regarding verbatim
3902 copying of that document.
3906 <simplesect id="fdl-section7">
3907 <title>7. AGGREGATION WITH INDEPENDENT WORKS</title>
3909 A compilation of the <link
3910 linkend="fdl-document">Document</link> or its derivatives with
3911 other separate and independent documents or works, in or on a
3912 volume of a storage or distribution medium, does not as a whole
3913 count as a <link linkend="fdl-modified">Modified Version</link>
3914 of the Document, provided no compilation copyright is claimed
3915 for the compilation. Such a compilation is called an
3916 <quote>aggregate</quote>, and this License does not apply to the
3917 other self-contained works thus compiled with the Document , on
3918 account of their being thus compiled, if they are not themselves
3919 derivative works of the Document. If the <link
3920 linkend="fdl-cover-texts">Cover Text</link> requirement of <link
3921 linkend="fdl-section3">section 3</link> is applicable to these
3922 copies of the Document, then if the Document is less than one
3923 quarter of the entire aggregate, the Document's Cover Texts may
3924 be placed on covers that surround only the Document within the
3925 aggregate. Otherwise they must appear on covers around the whole
3930 <simplesect id="fdl-section8">
3931 <title>8. TRANSLATION</title>
3933 Translation is considered a kind of modification, so you may
3934 distribute translations of the <link
3935 linkend="fdl-document">Document</link> under the terms of <link
3936 linkend="fdl-section4">section 4</link>. Replacing <link
3937 linkend="fdl-invariant"> Invariant Sections</link> with
3938 translations requires special permission from their copyright
3939 holders, but you may include translations of some or all
3940 Invariant Sections in addition to the original versions of these
3941 Invariant Sections. You may include a translation of this
3942 License provided that you also include the original English
3943 version of this License. In case of a disagreement between the
3944 translation and the original English version of this License,
3945 the original English version will prevail.
3949 <simplesect id="fdl-section9">
3950 <title>9. TERMINATION</title>
3952 You may not copy, modify, sublicense, or distribute the <link
3953 linkend="fdl-document">Document</link> except as expressly
3954 provided for under this License. Any other attempt to copy,
3955 modify, sublicense or distribute the Document is void, and will
3956 automatically terminate your rights under this License. However,
3957 parties who have received copies, or rights, from you under this
3958 License will not have their licenses terminated so long as such
3959 parties remain in full compliance.
3963 <simplesect id="fdl-section10">
3964 <title>10. FUTURE REVISIONS OF THIS LICENSE</title>
3966 The <ulink type="http"
3967 url="http://www.gnu.org/fsf/fsf.html">Free Software
3968 Foundation</ulink> may publish new, revised versions of the GNU
3969 Free Documentation License from time to time. Such new versions
3970 will be similar in spirit to the present version, but may differ
3971 in detail to address new problems or concerns. See <ulink
3973 url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>.
3977 Each version of the License is given a distinguishing version
3978 number. If the <link linkend="fdl-document">Document</link>
3979 specifies that a particular numbered version of this License
3980 <quote>or any later version</quote> applies to it, you have the
3981 option of following the terms and conditions either of that
3982 specified version or of any later version that has been
3983 published (not as a draft) by the Free Software Foundation. If
3984 the Document does not specify a version number of this License,
3985 you may choose any version ever published (not as a draft) by
3986 the Free Software Foundation.
3993 <!-- Keep this comment at the end of the file
3998 sgml-namecase-general:t
3999 sgml-general-insert-case:lower
4000 sgml-minimize-attributes:nil
4001 sgml-always-quote-attributes:t
4003 sgml-indent-data:nil
4004 sgml-parent-document:nil
4005 sgml-exposed-tags:nil
4006 sgml-local-catalogs:nil
4007 sgml-local-ecat-files:nil