updated the revision history to show an increase in version number
[fspm_howto] / FreeSoftwareProjectManagementHOWTO.sgml
1 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
2
3 <article>
4
5 <!-- Header -->
6
7  <artheader>
8   <title>Free Software Project Management HOWTO</title>
9   
10   <author>
11    <firstname>Benjamin</firstname>
12    <othername>"Mako"</othername>
13    <surname>Hill</surname>
14    <affiliation>
15     <address>
16       <email>mako@debian.org</email>
17     </address>
18    </affiliation>
19   </author>
20
21   <revhistory>
22    <revision>
23     <revnumber>v0.3.1</revnumber>
24     <date>18 June 2001</date>
25     <authorinitials>bch</authorinitials>
26    </revision>
27
28    <revision>
29     <revnumber>v0.3</revnumber>
30     <date>5 May 2001</date>
31     <authorinitials>bch</authorinitials>
32    </revision>
33
34    <revision>
35     <revnumber>v0.2.1</revnumber>
36     <date>10 April 2001</date>
37     <authorinitials>bch</authorinitials>
38    </revision>
39
40    <revision>
41     <revnumber>v0.2</revnumber>
42     <date>8 April 2001</date>
43     <authorinitials>bch</authorinitials>
44    </revision>
45
46    <revision>
47     <revnumber>v0.01</revnumber>
48     <date>27 March 2001</date>
49     <authorinitials>bch</authorinitials>
50     <revremark>Initial Release</revremark>
51    </revision>
52   </revhistory>
53
54   <abstract>
55    <indexterm>
56     <primary>fswd</primary>
57    </indexterm>
58    
59    <para>
60     This HOWTO is designed for people with experience in programming
61     and some skills in managing a software project but who are new to
62     the world of free software. This document is meant to act as a
63     guide to the non-technical aspects of free software project
64     management and was written to be a crash course in the people
65     skills that aren't taught to commercial coders but that can make
66     or break a free software project.
67    </para>
68   </abstract>
69   
70  </artheader>
71
72 <!-- Section1: intro -->
73
74  <sect1 id="intro">
75   <title>Introduction</title>
76   
77   <indexterm>
78    <primary>fswd!introduction</primary>
79   </indexterm>
80   
81   <para>
82    Skimming through freshmeat.net provides mountains of reasons for this
83    HOWTO's existence--the Internet is littered with excellently
84    written and useful programs that have faded away into the universe
85    of free software forgottenness. This dismal scene made me ask
86    myself, "Why?"
87   </para>
88
89   <para>
90    This HOWTO tries to do a lot of things (probably too many), but it
91    can't answer that question and won't attempt it. What this HOWTO
92    will attempt to do is give your Free Software project a fighting
93    chance--an edge. If you write a piece of crap that no one is
94    interested in, you can read this HOWTO until you can recite it in
95    your sleep and your project will probably fail. Then again, you can
96    write a beautiful, relevant piece of software and follow every
97    instruction in this HOWTO and your software may still not make
98    it. Sometimes life is like that. However, I'll go out a limb and
99    say that if you write a great, relevant pieces of software and
100    ignore the advise in this HOWTO, you'll probably fail <emphasis>
101    more often</emphasis>.
102   </para>
103
104   <para>
105    A lot of the information in this HOWTO is best called common
106    sense. Of course, as any debate on interfaces will prove, what is
107    common sense to some programmers proves totally unintuitive to
108    others. After explaining bits and pieces of this HOWTO to Free
109    Software developers on several occasions, I realized that writing
110    this HOWTO might provide a useful resource and a forum for
111    programmers to share ideas about what has and has not worked for
112    them.
113   </para>
114
115   <para>
116    As anyone involved in any of what seems like an unending parade of
117    ridiculous intellectual property clashes will attest to, a little
118    bit of legalese proves important.
119   </para>
120
121 <!-- Section2: copyright -->
122
123   <sect2 id="copyright">
124    <title>Copyright Information</title>
125
126    <para>
127     This document is copyrighted (c) 2000 Benjamin (Mako) Hill and is
128     distributed under the terms of the <citetitle>GNU Free
129     Documentation License</citetitle>.
130    </para>
131
132     <para>
133      Permission is granted to copy, distribute and/or modify this
134      document under the terms of the <link
135      linkend="fdl"><citetitle>GNU Free Documentation
136      License</citetitle></link>, Version 1.1 or any later version
137      published by the Free Software Foundation with no Invariant
138      Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy
139      of the license can be found in <xref linkend="fdl">.
140     </para>
141   </sect2>
142
143 <!-- Section2: disclaimer -->
144
145   <sect2 id="disclaimer">
146    <title>Disclaimer</title>
147
148    <para>
149     No liability for the contents of this documents can be accepted.
150     Use the concepts, examples and other content at your own risk.  As
151     this is a new edition of this document, there may be errors and
152     inaccuracies, that may of course be damaging to your project (and
153     potentially your system).  Proceed with caution, and although this
154     is highly unlikely, the author(s) does not take any responsibility
155     for that.
156    </para>
157
158    <para>
159     All copyrights are held by their by their respective owners, unless
160     specifically noted otherwise.  Use of a term in this document
161     should not be regarded as affecting the validity of any trademark
162     or service mark.
163    </para>
164
165    <para>
166     Naming of particular products or brands should not be seen 
167     as endorsements.
168    </para>
169
170   </sect2>
171
172 <!-- Section2: newversions-->
173
174   <sect2 id="newversions">
175    <title>New Versions</title>
176
177    <para>
178     This version is the part of the third pre-release cycle of this
179     HOWTO. It is written to be released to developers for critique and
180     brainstorming. Please keep in mind that this version of the HOWTO
181     is still in an infant stage and will continue to be revised
182     extensively.
183    </para>
184
185    <para>
186     The latest version number of this document should always be listed
187     on <ulink url="http://yukidoke.org/~mako/projects/howto">the projects
188     homepage </ulink> hosted by <ulink url="http://yukidoke.org">yukidoke.org.</ulink>
189    </para>
190
191    <para>
192     The newest version of this HOWTO will always be made available at
193     the same website, in a variety of formats:
194    </para>
195
196    <para>
197    <itemizedlist>
198
199     <listitem>
200      <para>
201       <ulink url="http://yukidoke.org/~mako/projects/howto/FreeSoftwareProjectManagement-HOWTO/t1.html">HTML</ulink>.
202      </para>
203     </listitem>
204
205
206     <listitem>
207      <para>
208       <ulink url="http://yukidoke.org/~mako/projects/howto/FreeSoftwareProjectManagement-HOWTO.html">HTML (single page)</ulink>.
209      </para>
210     </listitem>
211
212     <listitem>
213      <para>
214       <ulink URL="http://yukidoke.org/~mako/projects/howto/FreeSoftwareProjectManagement-HOWTO.txt">plain text</ulink>.
215      </para>
216     </listitem>
217
218     <listitem>
219      <para>
220       <ulink url="http://yukidoke.org/~mako/projects/howto/FreeSoftwareProjectManagement-HOWTO.ps.gz">Compressed postscript</ulink>.
221      </para>
222     </listitem>
223
224     <listitem>
225      <para>
226       <ulink url="http://yukidoke.org/~mako/projects/howto/FreeSoftwareProjectManagement-HOWTO.sgml.gz">Compressed SGML source</ulink>.
227      </para>
228     </listitem>
229    </itemizedlist>
230    </para>
231   </sect2>
232
233 <!-- Section2: credits -->
234
235   <sect2 id="credits">
236    <title>Credits</title>
237
238    <para>
239     In this version I have the pleasure of acknowledging:
240    </para>
241
242    <para>
243     Anyone who gave me an idea for a better name and everyone who
244     assured me that a <citetitle>Project Management HOWTO</citetitle>
245     didn't necessary sound corporate.
246    </para>
247
248    <para>
249     Josh Crawford, Andy King, and Jaime Davila who all read through
250     this in entirety and gave me feedback that has helped me make
251     changes and improvements to this document. I can't thank you guys
252     enough for your help. An extra <quote>Thank You</quote> goes to
253     Andy King who who read through this several times and submitted
254     patches to make life easier for me.
255    </para>
256
257    <para>
258     Karl Fogel, the author of <citetitle>Open Source Development with
259     CVS</citetitle> published by the Coriolis Open Press. Large parts
260     of his book are available <ulink
261     url="http://cvsbook.red-bean.com">on the web</ulink>. 225 pages of
262     the book are available under the GPL and constitute the best
263     tutorial on CVS I've ever seen. The rest of the book covers,
264     <quote>the challenges and philosophical issues inherent in running
265     an Open Source project using CVS.</quote> The book does a good job
266     of covering some of the subjects brought up in this HOWTO and much
267     more. <ulink url="http://cvsbook.red-bean.com">The book's
268     website</ulink> has information on ordering the book and provides
269     several translations of the chapters on CVS. If you are seriously
270     interested in running a Free Software project, you want this
271     book. I tried to mention Fogel in sections of this HOWTO where I
272     knew I was borrowing directly from his ideas. If I missed any, I'm
273     sorry. I'll try and have those fixed in future versions.
274    </para>
275    
276    <para>
277     Karl Fogel can be reached at <email>kfogel (at) red-bean (dot)
278     com</email>
279    </para>
280
281    <para>
282     Also providing support material, and inspiration for this HOWTO is
283     Eric S. Raymond for his prolific, consistent, and carefully
284     crafted arguments and Lawrence Lessig for reminding me of the
285     importance of Free Software. Additionaly, I want to thank every
286     user and developer involved with the <ulink
287     url="http://www.debian.org">Debian Project</ulink>. The project
288     has provided me with a home, a place to practice free software
289     advocacy, a place to make a difference, a place to learn from
290     those who have been involved with the movement much longer than I,
291     and proof of a free software project that definitely, definitely
292     works.
293    </para>
294
295    <para>
296     Above all, I want to thank <emphasis>Richard Stallman</emphasis>
297     for his work at the Free Software Foundation and for never giving
298     up. Stallman provides and articulates the philosophical basis that
299     attracts me to free software and that drives me towards writing a
300     document to make sure it succeeds. RMS can always be emailed at
301     <email>rms (at) gnu (dot) org</email>.
302    </para>
303
304   </sect2>
305
306 <!-- Section2: feedback -->
307
308   <sect2 id="feedback">
309    <title>Feedback</title>
310
311    <para>
312     Feedback is always and most certainly welcome for this
313     document. Without your submissions and input, this document
314     wouldn't exist. Do you feel that something is missing? Don't
315     hesitate to contact me to have me write a chapter, section, or
316     subsection or to write one yourself. I want this document to be a
317     product of the Free Software development process that it heralds
318     and I believe that its ultimate success will be rooted in its
319     ability to do this. Please send your additions, comments, and
320     criticisms to the following email address:
321     <email>mako@debian.org</email>.
322    </para>
323    </sect2>
324
325 <!-- Section2: translations -->
326
327   <sect2 id="translations">
328    <title>Translations</title>
329
330    <para>
331     I know that not everyone speaks English. Translations are nice and
332     I'd love for this HOWTO to gain the kind of international reach
333     afforded by translated versions.
334    </para>
335
336    <para>
337     However, this HOWTO is still young and I have to yet to be
338     contacted about a translation so English is all that is currently
339     available. If you would like to help with or do a translation, you
340     will gain my utmost respect and admiration and you'll get to be
341     part of a cool process. If you are at all interested, please don't
342     hesitate to contact me at: <email>mako@debian.org</email>.
343    </para>
344    </sect2>
345  </sect1>
346
347 <!-- Section1: intro: END -->
348
349 <!-- Section1: starting -->
350
351  <sect1 id="starting">
352   <title>Starting a Project</title>
353
354    <indexterm>
355     <primary>fswd!starting</primary>
356    </indexterm>
357   <para>
358    With very little argument, the beginning is the most difficult
359    period in a project's life to do successful free software project
360    managment. Laying a firm foundation will determine whether your
361    project flourishes or withers away and dies. It is also the subject
362    that is of most immediate interest to anyone reading this document
363    as a tutorial.
364   </para>
365
366   <para>
367    Starting a project involves a dilemma that you as a developer must
368    try and deal with: no potential user for your program is interested
369    in a program that doesn't work, while the development process that
370    you want to employ holds involvement of users as imperative.
371   </para>
372
373   <para>
374    It is in these dangerous initial moments that anyone working to
375    start a free software project must try and strike a balance along
376    these lines. One of the most important ways that someone trying to
377    start a project can work towards this balance is by establishing a
378    solid framework for the development process through some of the
379    suggestions mentioned in this section.
380   </para>
381
382
383 <!-- Section2: chooseproject-->
384
385   <sect2 id="chooseproject">
386    <title>Choosing a Project</title>
387
388    <para>
389     If you are reading this document, there's a good chance you
390     already have an idea for a project in mind. Chances are also
391     pretty good that it fills a percieved gap by doing something that
392     no other free software project does or by doing something in a way
393     that is unique enough to necessitate a brand new piece of
394     software.
395    </para>
396
397    <sect3 id=identifyidea>
398     <title>Identify and articulate your idea</title>
399     <para>
400      Eric S. Raymond writes about how free software projects start in
401      his essay, <ulink
402      url="http://www.tuxedo.org/~esr/writings/cathedral-bazaar/"><quote>The
403      Cathedral and the Bazaar,</quote></ulink> which comes as required
404      reading for any free software developer. It is available online .
405     </para>
406
407     <para>
408      In <quote>The Cathedral and the Bazaar,</quote> Raymond tells us
409      that: <quote>every good work of software starts by scratching
410      a developers itch.</quote> Raymond's now widely accepted
411      hypothesis is that new free software programs are written, first
412      and foremost, to solve a specific problem facing the developer.
413     </para>
414
415     <para>
416      If you have an idea for a program in mind, chances are good that
417      it targets a specific problem or <quote>itch</quote> you want to
418      see scratched. <emphasis>This idea is the project.</emphasis>
419      Articulate it clearly. Write it out. Describe the problem you
420      will attack in detail. The success of your project in tackling a
421      particular problem will be tied to your ability to identify that
422      problem clearly early on. Find out exactly what it is that you
423      want your project to do.
424     </para>
425
426     <para>
427      Monty Manley articulates the importance of this initial step in
428      an essay, <quote><ulink
429      url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
430      Projects the Open Source Way.</ulink></quote> As the next section
431      will show, there is <emphasis>a lot</emphasis> of work that needs
432      to be done before software is even ready to be coded. Manley
433      says, <quote>Beginning an OSS project properly means that a
434      developer must, first and foremost, avoid writing code too
435      soon!</quote>
436     </para>
437    </sect3>
438
439    <sect3 id=evalulateidea>
440     <title>Evaluate your idea</title>
441
442     <para>
443      In evaluating your idea, you need to first ask yourself a few
444      questions.  This should happen before you move any further
445      through this HOWTO. Ask yourself: <emphasis>Is the free software
446      development model really the right one for your
447      project?</emphasis>
448     </para>
449
450     <para>
451      Obviously, since the program scratches your itch, you are
452      definitely interested in seeing it implemented in code. But,
453      because one hacker coding in solitude fails to qualify as a free
454      software development effort, you need to ask yourself a second
455      question: <emphasis>Is anybody else interested?</emphasis>
456     </para>
457
458     <para>
459      Sometimes the answer is a simple <quote>no.</quote> If you want
460      to write a set of scripts to sort <emphasis>your</emphasis>
461      <acronym>MP3</acronym> collection on <emphasis>your</emphasis>
462      machine, <emphasis>maybe</emphasis> the free software development
463      model is not the best one to choose. However, if you want to
464      write a set of scripts to sort <emphasis>anyone's</emphasis>
465      <acronym>MP3</acronym>s, a free software project might fill a
466      useful gap.
467     </para>
468
469     <para>
470      Luckily, the Internet is a place so big and so diverse that,
471      chances are, there is someone, somewhere, who shares your
472      interests and who feels the same <quote>itch.</quote> It is the
473      fact that there are so many people with so many similar needs and
474      desires that introduces the third major question: <emphasis>Has
475      somebody already had your idea or a reasonably similar
476      one?</emphasis>
477     </para>
478
479      <sect4 id=evalwhere>
480       <title>Finding Similar Projects</title>
481
482      <para>
483       There are places you can go on the web to try and answer the
484       question above. If you have experience with the free software
485       community, you are probably already familiar with many of these
486       sites. All of the resources listed below offer searching of
487       their databases:
488      </para>
489
490      <para>
491      <variablelist>
492        <varlistentry>
493         <term>freshmeat.net</term>
494         <listitem>
495          <para><ulink url="http://freshmeat.net">freshmeat.net</ulink>
496          describes itself as, <quote>the Web's largest index of Linux
497          and Open Source software</quote> and its reputation along
498          these lines is totally unparalleled and unquestioned. If you
499          can't find it on freshmeat, its doubtful that you (or anyone
500          else) will find it at all.</para>
501         </listitem>
502        </varlistentry>
503
504        <varlistentry>
505         <term>Slashdot</term>
506         <listitem>
507          <para><ulink url="http://slashdot.org">Slashdot</ulink>
508          provides <quote>News for Nerds. Stuff that matters,</quote>
509          which usually includes discussion of free software, open
510          source, technology, and geek culture news and events. It is
511          not unusual for a particularly sexy development effort to be
512          announced here, so it is definitely worth checking.</para>
513         </listitem>
514        </varlistentry>
515
516        <varlistentry>
517         <term>SourceForge</term>
518         <listitem>
519          <para><ulink url="http://sourceforge.net">SourceForge</ulink>
520          houses and facilitates a growing number of open source and
521          free software projects. It is also quickly becoming a nexus
522          and a necessary stop for free software
523          developers. SourceForge's <ulink
524          url="http://sourceforge.net/softwaremap/trove_list.php">software
525          map</ulink> and <ulink url="http://sourceforge.net/new/"> new
526          release</ulink> pages should be necessary stops before
527          embarking on a new free software project. SourceForge also
528          provides a <ulink
529          url="http://sourceforge.net/snippet/">Code Snippet
530          Library</ulink> which contains useful reusable chunks of code
531          in an array of languages which can come in useful in any
532          project.</para>
533         </listitem>
534        </varlistentry>
535
536        <varlistentry>
537         <term>Google and Google's Linux Search</term>
538         <listitem>
539          <para><ulink url="http://www.google.com">Google</ulink> and
540          <ulink url="http://www.google.com/linux"> Google's Linux
541          Search</ulink>, provides powerful web searches that may reveal
542          people working on similar projects. It is not a catalog of
543          software or news like freshmeat or Slashdot, but it is worth
544          checking to make sure you aren't pouring your effort into a
545          redundant project.</para>
546         </listitem>
547        </varlistentry>
548
549       </variablelist>
550      </para>
551     </sect4>
552
553     <sect4 id=evalhow>
554      <title>Deciding to Proceed</title>
555      <para>
556       Once you have successfully charted the terrain and have an idea
557       about what kinds of similar free software projects exist, every
558       developer needs to decide whether to proceed with their own
559       project. It is rare that a new project seeks to accomplish a
560       goal that is not at all similar or related to the goal of
561       another project. Anyone starting a new project needs to ask
562       themselves: <quote>Will the new project be duplicating work done
563       by another project? Will the new project be competing for
564       developers with an existing project? Can the goals of the new
565       project be accomplished by adding functionality to an existing
566       project?</quote>
567      </para>
568
569      <para>
570       If the answer to any of these questions is <quote>yes,</quote>
571       try to contact the developer of the existing project(s) in
572       question and see if he or she might be willing to collaborate
573       with you.
574      </para>
575
576      <para>
577       For many developers this may be the single most difficult aspect
578       of free software project managment, but it is an essential one. It is
579       easy to become fired up by an idea and get caught up in the
580       momentum and excitement of a new project. It is often extremely
581       difficult to do, but it is important that any free software
582       developer remembers that the best interests of the free software
583       community and the quickest way to accomplish your own project's
584       goals and the goals of similar projects can often be
585       accomplished by <emphasis>not</emphasis> starting a new
586       development effort.
587      </para>
588
589     </sect4>
590    </sect3>
591   </sect2>
592
593 <!-- Section2: naming-->
594
595   <sect2 id="naming">
596    <title>Naming your project</title>
597
598    <para>
599     While there are plenty of projects that fail with descriptive
600     names and plenty that succeed without them, I think naming your
601     project is worth giving a bit of thought. Leslie Orchard tackles
602     this issue in an <ulink
603     url="http://www.advogato.org/article/67.html">Advogato
604     article</ulink>. His article is short and definately worth looking
605     over quickly.
606    </para>
607
608    <para>
609     The synopsis is that Orchard recommends you pick a name where,
610     after hearing the name, many users or developers will both:
611    </para>
612
613    <para>
614     <itemizedlist>
615      <listitem>
616       <para>Know what the project does.</para>
617      </listitem>
618      <listitem>
619       <para>Remember it tomorrow.</para>
620      </listitem>
621     </itemizedlist>
622    </para>
623
624    <para>
625     Humorously, Orchard's project, <quote>Iajitsu,</quote> does
626     neither. It is probably unrelated that development has effectively
627     frozen since the article was written.
628    </para>
629
630    <para>
631     He makes a good point though. There are companies whose only job
632     is to make names for pieces of software. They make
633     <emphasis>ridiculous</emphasis> amount of money doing it and are
634     supposedly worth it. While you probably can't aford a company like
635     this, you can afford to learn from their existance and think a
636     little bit about the name you are giving your project because it
637     <emphasis>does</emphasis> matter.
638    </para>
639
640    <para>
641     If there is a name you really want but it doesn't fit Orchard's
642     criteria, you can still go ahead. I thought <quote>gnubile</quote>
643     was one of the best I'd heard for a free software project ever and
644     I still talk about it long after I've stopped using the
645     program. However, if you can be flexible on the subject, listen to
646     Orchard's advice. It might help you.
647    </para>
648   </sect2>
649
650 <!-- Section2: licensing-->
651
652   <sect2 id="licensing">
653    <title>Licensing your Software</title>
654    
655    <para>
656     On one (somewhat simplistic) level, the difference between a piece
657     of free software and a piece of propriety software is the
658     license. A license helps you as the developer by protecting your
659     legal rights to have your software distributed under your terms
660     and helps demonstrate to those who wish to help you or your
661     project that they are encouraged to join.
662    </para>
663    
664    <sect3 id="chooselicense">
665     <title>Choosing a license</title>
666
667     <para>
668      Any discussion of licenses is also sure to generate at least a
669      small flame war as there are strong feelings that some free
670      software licenses are better than others. This discussion also
671      brings up the question of <quote>Open Source Software</quote> and
672      the debate over the terms <quote>Open Source Software</quote> and
673      <quote>Free Software</quote>. However, because I've written the
674      Free Software Project Management HOWTO and not the Open Source
675      Software Project Management HOWTO, my own allegiances in this
676      argument are in the open.
677     </para>
678
679     <para>
680      In attempting to reach a middle ground through diplomacy without
681      sacrificing my own philosophy, I will recommend picking any
682      license that conforms to the <ulink
683      url="http://www.debian.org/social_contract">Debian Free Software
684      Guidelines</ulink>. Originally compiled by the Debian project
685      under Bruce Perens, the <acronym>DFSG</acronym> forms the first
686      version of the <ulink
687      url="http://www.opensource.org/docs/definition_plain.html">Open
688      Source Definition.</ulink> Examples of free licenses given by the
689      <acronym>DFSG</acronym> are the <acronym>GPL</acronym>, the
690      <acronym>BSD</acronym>, and the Artistic License.
691     </para>
692
693     <para>
694      Conforming to the definition of free software offered by Richard
695      Stallman in <ulink
696      url="http://www.gnu.org/philosophy/free-sw.html"><quote>The Free
697      Software Definition</quote></ulink>, any of these licenses will
698      uphold, <quote>users' freedom to run, copy, distribute, study,
699      change and improve the software.</quote> There are plenty of
700      other licenses that also conform to the <acronym>DFSG</acronym>
701      but sticking with a more well-known license will offer the advantage
702      of immediate recognition and understanding.
703     </para>
704
705     <para>
706      In attempting a more in-depth analysis, I agree with Karl Fogel's
707      description of licenses as falling into two groups: those that
708      are the <acronym>GPL</acronym> and those that are not the
709      <acronym>GPL</acronym>.
710     </para>
711
712     <para>
713      Personally, I license all my software under the
714      <acronym>GPL</acronym>. Created and protected by the Free
715      Software Foundation and the GNU Project, the
716      <acronym>GPL</acronym> is the license for the Linux kernel,
717      GNOME, Emacs, and the vast majority of GNU/Linux software. It's
718      the obvious choice but I also believe it is a good one. Any BSD
719      fanatic will urge you to remember that there is a viral aspect to
720      the <acronym>GPL</acronym> that prevents the mixture of
721      <acronym>GPL</acronym>'ed code with non-<acronym>GPL</acronym>'ed
722      code. To many people (myself included), this is a benefit, but to
723      some, it is a major drawback.
724     </para>
725
726     <para>
727      The three major licenses can be found at the following locations:
728     </para>
729
730     <para>
731      <itemizedlist>
732       <listitem>
733        <para><ulink url="http://www.gnu.org/copyleft/gpl.html">The GNU
734        General Public License</ulink></para>
735       </listitem>
736       <listitem>
737        <para><ulink url="http://www.debian.org/misc/bsd.license">The
738        BSD License</ulink></para>
739       </listitem>
740       <listitem>
741        <para><ulink
742        url="http://language.perl.com/misc/Artistic.html">The Artistic
743        License</ulink></para>
744       </listitem>
745      </itemizedlist>
746     </para>
747
748     <para>
749      <emphasis>In any case, please read through any license before
750      your release your software under it. As the primary developer,
751      you can't afford any license surprises.</emphasis>
752     </para>
753    </sect3>
754
755    <sect3 id="licensechoose">
756     <title>The mechanics of licensing</title>
757
758     <para>
759      The text of the <acronym>GPL</acronym> offers <ulink
760      url="http://www.gnu.org/copyleft/gpl.html#SEC4">a good
761      description of the mechanics of applying a license</ulink> to a
762      piece of software. My quick checklist for applying a license
763      includes:
764     </para>
765
766     <para>
767      <itemizedlist>
768      
769       <listitem>
770        <para>If at all possible, attach and distribute a full copy of
771        the license with the source and binary by including a separate
772        file.</para>
773       </listitem>
774
775       <listitem>
776        <para>At the top of each source file in your program, attach a
777        notice of copyright and include information on where the full
778        license can be found. The <acronym>GPL</acronym> recommends
779        that each file begin with:</para>
780
781        <screen>
782 <emphasis>one line to give the program's name and an idea of what it does.</emphasis>
783 Copyright (C) yyyy  name of author
784
785 This program is free software; you can redistribute it and/or
786 modify it under the terms of the GNU General Public License
787 as published by the Free Software Foundation; either version 2
788 of the License, or (at your option) any later version.
789
790 This program is distributed in the hope that it will be useful,
791 but WITHOUT ANY WARRANTY; without even the implied warranty of
792 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
793 GNU General Public License for more details.
794
795 You should have received a copy of the GNU General Public License
796 along with this program; if not, write to the Free Software
797 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
798        </screen>
799
800        <para>
801         The <acronym>GPL</acronym> goes on to recommend attaching
802         information on methods for contacting you (the author) via
803         email or physical mail.
804       </para>
805       </listitem>
806
807       <listitem>
808        <para>
809         The <acronym>GPL</acronym> continues and suggests that if your
810         program runs in an interactive mode, you should write the
811         program to output a notice each time it enters interactive
812         mode that includes a message like this one that points to full
813         information about the programs license:
814        </para>
815
816        <screen>
817 Gnomovision version 69, Copyright (C) year name of author
818 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
819 type `show w'.  This is free software, and you are welcome
820 to redistribute it under certain conditions; type `show c' 
821 for details.
822        </screen>
823       </listitem>
824
825       <listitem>
826        <para>Finally, it might be helpful to include a
827        <quote>copyright disclaimer</quote> from an employer or a
828        school if you work as a programmer or if it seems like your
829        employer or school might be able to make an argument for
830        ownership of your code later on. These aren't often needed but
831        there are plenty of free software developers who have gotten
832        into trouble and wish they'd asked for one.</para>
833       </listitem>
834
835      </itemizedlist>
836     </para>    
837    </sect3>
838
839    <sect3 id="licensewarning">
840     <title>Final license warning</title>
841
842     <para>
843      Please, please, please, place your software under
844      <emphasis>some</emphasis> license. It may not seem important, and
845      to you it may not be, but licenses <emphasis>are</emphasis>
846      important. For a piece of software to be included in the Debian
847      GNU/Linux distribution, it must have a license that fits the
848      <ulink url="http://www.debian.org/social_contract">Debian Free
849      Software Guidelines</ulink>. If your software has no license, it
850      can not be distributed as a package in Debian until you
851      re-release it under a free license. Please save yourself and
852      others trouble by releasing the first version of your software
853      with a clear license.
854     </para>
855
856    </sect3>
857
858  </sect2>
859
860 <!-- Section2: chooseversioning-->
861
862   <sect2 id="chooseversioning">
863    <title>Choosing a Method of Version Numbering</title>
864
865    <para>
866     <emphasis>The most important thing about a system of version
867     numbering is that there is one.</emphasis> It may seem pedantic to
868     emphasize this point but you'd be surprised at the number of
869     scripts and small programs that pop up without any version number
870     at all.
871    </para>
872
873    <para>
874     <emphasis>The second most important thing about a system of
875     numbering is that the numbers always go up.</emphasis> Automatic
876     version tracking systems and people's sense of order in the
877     universe will fall apart if version numbers don't rise. It doesn't
878     <emphasis>really</emphasis> matter if 2.1 is a big jump and
879     2.0.005 is a small jump but it does matter that 2.1 is more recent
880     than 2.0.005.
881    </para>
882
883    <para>
884     Follow these two simple rules and you will not go (too)
885     wrong. Beyond this, the most common technique seems to be the
886     <quote>major level,</quote> <quote>minor level,</quote>
887     <quote>patch level</quote> version numbering scheme. Whether you
888     are familiar with the name or not, you interact with it all the
889     time. The first number is the major number and it signifies major
890     changes or rewrites. The second number is the minor number and it
891     represents added or tweaked functionality on top of a largely
892     coherant structure. The third number is the patch number and it
893     usually will only refer to releases fixing bugs.
894    </para>
895
896    <para>
897     The widespread use of this scheme is why I know the nature and
898     relative degree in the differences between a 2.4.12 release of the
899     Linux kernel and a 2.4.11, 2.2.12, and 1.2.12 without knowning
900     anything about any of the releases.
901    </para>
902
903    <para>
904     You can bend or break these rules, and people do. But beware, if
905     you choose to, someone will get annoyed, assume you don't know,
906     and try and educate you, probably not nicely. I always follow this
907     method and I implore you to do so as well.
908    </para>
909    
910    <para>
911     There are several version numbering systems that are well known,
912     useful, and that might be worth looking into before you release
913     your first version.
914    </para>
915
916    <variablelist>
917     <varlistentry>
918      <term>Linux kernel version numbering:</term>
919      <listitem>
920       <para>The Linux kernel uses a versioning system where any odd
921       minor version number refers to an development or testing release
922       and any even minor version number refers to a stable
923       version. Think about it for a second. Under this system, 2.1 and
924       2.3 kernels were and always will be development or testing
925       kernels and 2.0, 2.2. and 2.4 kernels are all production code
926       with a higher degree of stability and more testing.
927      </para>
928
929       <para>
930        Whether you plan on having a split development model (as
931        described in <xref linkend="branches">) or only one version
932        released at a time, my experience with several free software
933        projects and with the Debian project has taught me that use of
934        Linux's version numbering system is worth taking into
935        consideration. In Debian, <emphasis>all</emphasis> minor
936        versions are stable distributions (2.0, 2.1, etc). However,
937        many people assume that 2.1 is an unstable or development
938        version and continue to use an older version until they get so
939        frustrated with the lack of development progress that they
940        complain and figure the system out. If you never release an odd
941        minor version but only release even ones, nobody is hurt, and
942        less people are confused. It's an idea worth taking into
943        consideration.
944       </para>
945      </listitem>
946     </varlistentry>
947
948     <varlistentry>
949      <term>Wine version numbering:</term>
950      <listitem>
951       <para>Because of the unusual nature of wine's development where
952       the not-emulator is constantly improving but not working towards
953       any immediately achievable goal, wine is released every three
954       weeks. Wine does this by labeling their releases in <quote>Year
955       Month Day</quote> format where each release might be labeled
956       <quote>wine-XXXXXXXX</quote> where the version from January 04,
957       2000 would be <quote>wine-20000104</quote>. For certain
958       projects, <quote>Year Month Day</quote> format can make a lot of
959       sense.
960       </para>
961      </listitem>
962     </varlistentry>
963
964     <varlistentry>
965      <term>Mozilla milestones:</term>
966      <listitem>
967       <para>When one considers Netscape 6 and vendor versions, the
968       mozilla's project development structure is one of the most
969       complex free software models available. The project's version
970       numbering has reflected the unique situation in which it is
971       developed.
972       </para>
973
974       <para>
975        Mozilla's version numbering structure has historically been
976        made up of milestones. From the beginning of the mozilla
977        project, the goals of the project in the order and degree to
978        which they were to be achieved were charted out on a series of
979        <ulink url="http://www.mozilla.org/roadmap.html">road
980        maps</ulink>. Major points and achievements along these
981        road-maps were marked as milestones. Therefore, although
982        mozilla was built and distributed nightly as <quote>nightly
983        builds,</quote> on a day when the goals of a milestone on the
984        road-map had been reached, that particular build was marked as
985        a <quote>milestone release.</quote>
986       </para>
987
988       <para>
989        While I haven't seen this method employed in any other projects
990        to date, I like the idea and think that it might have value in
991        any testing or development branch of a large application under
992        heavy development.
993       </para>
994      </listitem>
995     </varlistentry>
996
997    </variablelist>
998   </sect2>
999
1000 <!-- Section2: documentation-->
1001
1002   <sect2 id="documentation">
1003    <title>Documentation</title>
1004
1005    <para>
1006     A huge number of otherwise fantastic free software applications
1007     have withered and died because their author was the only person
1008     who knew how to use them fully. Even if your program is written
1009     primarily for a techno-savvy group of users, documentation is
1010     helpful and even necessary for the survival of your project. You
1011     will learn later in <xref linkend="releasing"> that you should
1012     always release something that is usable. <emphasis>A piece of
1013     software without documentation is not usable.</emphasis>
1014    </para>
1015
1016    <para>
1017     There are lots of different people you should document for and
1018     there are lots of ways to document your project. <emphasis>The
1019     importance of documentation in source code to help facilitate
1020     development by a large community is vital</emphasis> but it falls
1021     outside the scope of this HOWTO. This being the case, this section
1022     deals with useful tactics for user-directed documentation.
1023    </para>
1024
1025    <para>
1026     A combination of tradition and necessity has resulted in a
1027     semi-regular system of documentation in most free software
1028     projects that is worth following. Both users and developers expect
1029     to be able to get documentation in several ways and it's essential
1030     that you provide the information they are seeking in a form they
1031     can read if your project is ever going to get off the
1032     ground. People have come to expect:
1033    </para>
1034
1035    <sect3>
1036     <title>Man pages</title> 
1037
1038     <para>Your users will want to be able to type <quote>man
1039     yourprojectname</quote> end up with a nicely formatted man page
1040     highlighting the basic use of your application. Make sure that
1041     before you release your program, you've planned for this.
1042     </para>
1043
1044     <para>
1045      Man pages are not difficult to write. There is excellent
1046      documentation on the man page writing process available through
1047      the <quote>The Linux Man-Page-HOWTO</quote> which is available
1048      through the Linux Documentation project <acronym>(LDP)</acronym>
1049      and is written by Jens Schweikhardt. It is available <ulink
1050      url="http://www.schweikhardt.net/man_page_howto.html">from
1051      Schweikhardt's site</ulink> or <ulink
1052      url="http://www.linuxdoc.org/HOWTO/mini/Man-Page.html">from the
1053      <acronym>LDP</acronym></ulink>.
1054     </para>
1055
1056     <para>
1057      It is also possible to write man pages using DocBook
1058      SGML. Because man pages are so simple and the DocBook method
1059      relatively new, I have not been able to follow this up but would
1060      love help from anyone who can give me more information on how
1061      exactly how this is done.
1062     </para>
1063    </sect3>
1064
1065    <sect3>
1066     <title>Command line accessible documentation</title>
1067
1068     <para>
1069      Most users will expect some basic amount of documentation to be
1070      easily available from the command line. For few programs should
1071      this type of documentation extend for more than one screen (24 or
1072      25 lines) but it should cover the basic usage, a brief (one or
1073      two sentence) description of the program, a list of the commands
1074      with explanations, as well as all the major options (also with
1075      explanations), plus a pointer to more in-depth documentation for
1076      those who need it. The command line documentation for Debian's
1077      apt-get serves as an excellent example and a useful model:
1078     </para>
1079
1080     <screen>
1081 apt 0.3.19 for i386 compiled on May 12 2000  21:17:27
1082 Usage: apt-get [options] command
1083        apt-get [options] install pkg1 [pkg2 ...]
1084
1085 apt-get is a simple command line interface for downloading and
1086 installing packages. The most frequently used commands are update
1087 and install.
1088
1089 Commands:
1090    update - Retrieve new lists of packages
1091    upgrade - Perform an upgrade
1092    install - Install new packages (pkg is libc6 not libc6.deb)
1093    remove - Remove packages
1094    source - Download source archives
1095    dist-upgrade - Distribution upgrade, see apt-get(8)
1096    dselect-upgrade - Follow dselect selections
1097    clean - Erase downloaded archive files
1098    autoclean - Erase old downloaded archive files
1099    check - Verify that there are no broken dependencies
1100
1101 Options:
1102   -h  This help text.
1103   -q  Loggable output - no progress indicator
1104   -qq No output except for errors
1105   -d  Download only - do NOT install or unpack archives
1106   -s  No-act. Perform ordering simulation
1107   -y  Assume Yes to all queries and do not prompt
1108   -f  Attempt to continue if the integrity check fails
1109   -m  Attempt to continue if archives are unlocatable
1110   -u  Show a list of upgraded packages as well
1111   -b  Build the source package after fetching it
1112   -c=? Read this configuration file
1113   -o=? Set an arbitary configuration option, eg -o dir::cache=/tmp
1114 See the apt-get(8), sources.list(5) and apt.conf(5) manual
1115 pages for more information and options.
1116     </screen>
1117
1118     <para>
1119      It has become a GNU convention to make this type of information
1120      accessible with the <quote>-h</quote> and the
1121      <quote>--help</quote> options. Most GNU/Linux users will expect
1122      to be able to retrieve basic documentation these ways so if you
1123      choose to use different methods, be prepared for the flames and
1124      fallout that may result.
1125     </para>
1126    </sect3>
1127
1128    <sect3>
1129     <title>Files users will expect</title>
1130     <para>
1131      In addition to man pages and command-line help, there are certain
1132      files where people will look for documentation, especially in any
1133      package containing source code. In a source distribution, most of
1134      these files can be stored in the root directory of the source
1135      distribution or in a subdirectory of the root called
1136      <quote>doc</quote> or <quote>Documentation.</quote> Common files
1137      in these places include:
1138     </para>
1139
1140     <para>
1141      <variablelist>
1142       <varlistentry>
1143        <term>README or Readme</term>
1144
1145        <listitem>
1146         <para>A document containing all the basic installation,
1147         compilation, and even basic use instructions that make up the
1148         bare minimum information needed to get the program up and
1149         running. A README is not your chance to be verbose but should
1150         be concise and effective. An ideal README is at least 30 lines
1151         long and more no more than 250.</para>
1152        </listitem>
1153
1154       </varlistentry>
1155       <varlistentry>
1156        <term>INSTALL or Install</term>
1157
1158        <listitem>
1159         <para>The INSTALL file should be much shorter than the README
1160         file and should quickly and concisely describe how to build
1161         and install the program. Usually an INSTALL file simply
1162         instructs the user to run <quote>./configure; make; make
1163         install</quote> and touches on any unusual options or actions
1164         that may be necessary. For most relatively standard install
1165         procedures and for most programs, INSTALL files are as short
1166         as possible and are rarely over 100 lines.</para>
1167        </listitem>
1168
1169       </varlistentry>
1170       <varlistentry>
1171        <term>CHANGELOG, Changelog, ChangeLog, or changelog</term>
1172
1173        <listitem>
1174         <para>A CHANGELOG is a simple file that every well-managed
1175         free software project should include. A CHANGELOG is simple
1176         the file that, as its name implies, logs or documents the
1177         changes you make to your program. The most simple way to
1178         maintain a CHANGELOG is to simply keep a file with the source
1179         code for your program and add a section to the top of the
1180         CHANGELOG with each release describing what has been changed,
1181         fixed, or added to the program. It's a good idea to post the
1182         CHANGELOG onto the website as well because it can help people
1183         decide whether they want or need to upgrade to a newer version
1184         or wait for a more significant improvement.</para>
1185        </listitem>
1186
1187       </varlistentry>
1188       <varlistentry>
1189        <term>NEWS</term>
1190
1191        <listitem>
1192         <para>A NEWS file and a ChangeLog are similar. Unlike a
1193         CHANGELOG, a NEWS file is not typically updated with new
1194         versions. Whenever new features are added, the developer
1195         responisble will make a note in the NEWS file. NEWS files
1196         should not have to be changed before a release (they should be
1197         kept up to date all along) but it's usually a good idea to
1198         check first anyway because often developers just forget to
1199         keep them as current as they should.</para>
1200        </listitem>
1201
1202       </varlistentry>
1203       <varlistentry>
1204        <term><acronym>FAQ</acronym></term>
1205
1206        <listitem>
1207         <para>For those of you that don't already know,
1208         <acronym>FAQ</acronym> stands for Frequently Asked Questions
1209         and a FAQ is a collection of exactly that. FAQs are not
1210         difficult to make. Simply make a policy that if you are asked
1211         a question or see a question on a mailing list two or more
1212         times, add the question (and its answer) to your FAQ. FAQs are
1213         more optional than the files listed above but they can save
1214         your time, increase usability, and decrease headaches on all
1215         sides.</para>
1216        </listitem>
1217
1218       </varlistentry>
1219      </variablelist>
1220     </para>
1221    </sect3>
1222
1223    <sect3>
1224     <title>Website</title> 
1225     <para>
1226      It's only indirectly an issue of documentation but a good website
1227      is quickly becoming an essential part of any free software
1228      project. Your website should provide access to your documentation
1229      (in <acronym>HTML</acronym> if possible). It should also include
1230      a section for news and events around your program and a section
1231      that details the process of getting involved with development or
1232      testing and make an open invitation. It should also supply links
1233      to any mailing lists, similar websites, and provide a direct link
1234      to all the available ways of downloading your software.
1235     </para>
1236    </sect3>
1237
1238    <sect3>
1239     <title>Other documentation hints</title>
1240
1241     <para>
1242      All your documentation should be in plaintext, or, in cases where
1243      it is on your website primarily, in HTML. Everyone can cat a
1244      file, everyone has a pager, (almost) everyone can render
1245      HTML. <emphasis>You are welcome to distribute information in PDF,
1246      PostScript, RTF, or any number of other widely used formats but
1247      this information must also be available in plaintext or HTML or
1248      people will be very angry at you.</emphasis>
1249     </para>
1250
1251     <para>
1252      It doesn't hurt to distribute any documentation for your program
1253      from your website (FAQs etc) with your program. Don't hesitate to
1254      throw any of this in the program's tarball. If people don't need
1255      it, they will delete it. I can repeat it over and over:
1256      <emphasis>Too much documentation is not a sin.</emphasis>
1257     </para>
1258    </sect3>
1259   </sect2>
1260
1261 <!-- Section2: presentation -->
1262
1263   <sect2 id="presentation">
1264    <title>Other Presentation Issues</title>
1265    <para>
1266     Many of the remaining issues surrounding the creation of a new
1267     free software program fall under what most people describe as
1268     common sense issues. Its often said that software engineering is
1269     90 percent common sense combined with 10 percent specialized
1270     knowledge. Still, they are worth noting briefly in hopes that they
1271     may remind a developer of something they may have forgotten.
1272    </para>
1273
1274    <sect3>
1275     <title>Package formats</title>
1276     <para>
1277      Package formats may differ depending on the system you are
1278      developing for. For windows based software, Zip archives (.zip)
1279      usually serve as the package format of choice. If you are
1280      developing for GNU/Linux, *BSD, or any UN*X, make sure that your
1281      source code is always available in tar'ed and gzip'ed format
1282      (.tar.gz). UNIX compress (.Z) has gone out of style and
1283      usefulness and faster computers have brought bzip2 (.bz2) into
1284      the spot-light as a more effective compression medium. I now make
1285      all my releases available in both gzip'ed and bzip2'ed tarballs.
1286     </para>
1287
1288     <para>
1289      Binary packages should always be distribution specific. If you
1290      can build binary packages against a current version of a major
1291      distribution, you will only make your users happy. Try to foster
1292      relationships with users or developers of large distributions to
1293      develop a system for the consistent creation of binary
1294      packages. It's often a good idea to provide RedHat
1295      <acronym>RPM</acronym>'s (.rpm), Debian deb's (.deb) and source
1296      <acronym>RPM</acronym>'s <acronym>SRPM</acronym>'s if
1297      possible. Remember: <emphasis>While these binaries packages are
1298      nice, getting the source packaged and released should always be
1299      your priority. Your users or fellow developers can and will do
1300      the the binary packages for you.</emphasis>
1301     </para>
1302    </sect3>
1303
1304    <sect3>
1305     <title>Version control systems</title>
1306
1307     <para>
1308      A version control system can make a lot of these problems of
1309      packaging (and a lot of other problems mentioned in this HOWTO)
1310      less problematic. If you are using *NIX, CVS is your best bet. I
1311      recommend Karl Fogel's book on the subject (and the <ulink
1312      url="http://cvsbook.red-bean.com/">posted HTML version</ulink>)
1313      wholeheartedly.
1314     </para>
1315
1316     <para>
1317      CVS or not, you should probably invest some time into learning
1318      about a version control system because it provides an automated
1319      way of solving many of the problems described by this HOWTO.  I
1320      am not aware of any free version control systems for Windows or
1321      MacOS but I know that CVS clients exist for both
1322      platforms. Websites like <ulink
1323      url="http://sourceforge.net">SourceForge</ulink> do a great job
1324      as well with a nice, easy-to-use web interface to CVS.
1325     </para>
1326
1327     <para>
1328      I'd love to devote more space in this HOWTO to CVS because I love
1329      it (I even use CVS to keep versions straight on this HOWTO!) but
1330      I think it falls outside the scope of this document and should have
1331      (already has) its own HOWTO.
1332     </para>
1333
1334    </sect3>
1335
1336    <sect3>
1337     <title>Useful tidbits and presentation hints</title>
1338
1339     <para>
1340      Other useful hints include:
1341     </para>
1342
1343     <para>
1344      <itemizedlist>
1345
1346       <listitem>
1347        <para>
1348         <emphasis>Make sure that your program can always be found in a
1349         single location.</emphasis> Often this means that you have a
1350         single directory accessible via <acronym>FTP</acronym> or the
1351         web where the newest version can be quickly recognized. One
1352         effective technique is a provide a symlink called
1353         <quote>yourprojectname-latest</quote> that is always pointing
1354         to the most recent released or development version of your
1355         free software application. Keep in mind that this location
1356         will recieve many requests for downloads around releases so
1357         make sure that the server you choose has adequate bandwidth.
1358        </para>
1359       </listitem>
1360
1361       <listitem>
1362        <para>
1363         <emphasis>Make sure that there is a consistent email address
1364         for bug reports.</emphasis> It's usually a good idea to make
1365         this something that is NOT your primary email address like
1366         yourprojectname@host or yourprojectname-bugs@host. This way,
1367         if you ever decide to hand over maintainership or if your
1368         email address changes, you simply need to change where this
1369         email address forwards. It also will allow for more than one
1370         person to deal with the influx of mail that is created if your
1371         project becomes as huge as you hope it will.
1372        </para>
1373       </listitem>
1374
1375      </itemizedlist>
1376     </para>
1377    </sect3>
1378   </sect2>
1379  </sect1>
1380
1381 <!-- Section1: starting: END -->
1382
1383 <!-- Section1: developers -->
1384
1385  <sect1 id="developers">
1386   <title>Maintaining a Project: Interacting with Developers</title>
1387   <indexterm>
1388    <primary>fswd!developers</primary>
1389   </indexterm>
1390
1391   <para>
1392    Once you have gotten your project started, you have overcome the
1393    most difficult hurdles in the development process of your
1394    program. Laying a firm foundation is essential, but the development
1395    process itself is equally important and provides just as many
1396    opportunities for failure. In the next two sections, I will
1397    describe running a project by discussing how to maintain a
1398    development effort through interactions with developers and with
1399    users.
1400   </para>
1401
1402   <para>
1403    In releasing your program, your program becomes free software. This
1404    transition is more than just a larger user base. By releasing your
1405    program as free software, <emphasis>your</emphasis> software
1406    becomes the <emphasis>free software community's</emphasis>
1407    software. The direction of your software's development will be
1408    reshaped, redirected, and fully determined by your users and, to a
1409    larger extent, by other developers in the community.
1410   </para>
1411
1412   <para>
1413    The major difference between free software development and
1414    propriety software development is the developer base. As the leader
1415    of a free software project, you need to attract and keep developers
1416    in a way that leaders of proprietary software projects simply don't
1417    have to worry about. <emphasis>As the person leading development of
1418    a free software project, you must harness the work of fellow
1419    developers by making responsible decisions and by responsibly
1420    choosing not to make decisions. You have to direct developers
1421    without being overbearing or bossy. You need to strive to earn
1422    respect and never forget to give it out.</emphasis>
1423   </para>
1424
1425 <!-- Section2: delegation  -->
1426
1427   <sect2 id="delegation">
1428    <title>Delegating Work</title>
1429
1430    <para>
1431     By now, you've hypothetically followed me through the early
1432     programming of a piece of software, the creation of a website and
1433     system of documentation, and we've gone ahead and (as will be
1434     discussed in <xref linkend="releasing">) released it to the rest
1435     of the world. Times passes, and if things go well, people become
1436     interested and want to help. The patches begin flowing in.
1437    </para>
1438
1439    <para>
1440     <emphasis>Like the parent of any child who grows up, it's now time
1441     to wince, smile and do most difficult thing in any parents
1442     life: It's time to let go.</emphasis>
1443    </para>
1444
1445    <para>
1446     Delegation is the political way of describing this process of
1447     <quote>letting go.</quote> It is the process of handing some of
1448     the responsibility and power over your project to other
1449     responsible and involved developers. It is difficult for anyone
1450     who has invested a large deal of time and energy into a project
1451     but it essential for the growth of any free software project. One
1452     person can only do so much. A free software project is nothing
1453     without the involvement of <emphasis>a group</emphasis> of
1454     developers. A group of developers can only be maintained through
1455     respectful and responsible leadership and delegation.
1456    </para>
1457
1458    <para>
1459     As your project progresses, you will notice people who are putting
1460     significant amounts of time and effort into your project. These
1461     will be the people submitting the most patches, posting most on
1462     the mailing lists, and engaging in long email discussions. It is
1463     your responsibility to contact these people and to try and shift
1464     some of the power and responsibility of your position as the
1465     project's maintainer onto them (if they want it). There are
1466     several easy ways you can do this:
1467    </para>
1468
1469    <para>
1470     In a bit of a disclaimer, delegation need not mean rule by
1471     comittee. In many cases it does and this has been proven to
1472     work. In other cases this has created problems. <ulink
1473     url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
1474     Projects the Open Source Way</ulink> argues that <quote>OSS
1475     projects do best when one person is the clear leader of a team and
1476     makes the big decisions (design changes, release dates, and so
1477     on).</quote> I think this often true but would urge developers to
1478     consider the ideas that the project leader need not be the
1479     project's founder and that these important powers need not all rest
1480     with one person but that a release manager may be different than a
1481     lead developer. These situations are tricky politically so
1482     be careful and make sure it's necessary before you go around
1483     empowering people.
1484    </para>
1485
1486    <sect3>
1487     <title>How to delegate</title>
1488  
1489     <para>
1490      You may find that other developers seem even more experienced or
1491      knowledgeable than you. Your job as a maintainer does not mean
1492      you have to be the best or the brightest. It means you
1493      are responsible for showing good judgment and for
1494      recognizing which solutions are maintainable and which are not. 
1495     </para>
1496     <para>
1497      Like anything, its easier to watch others delegate than to do it
1498      yourself. In a sentence: <emphasis>Keep an eye out for other
1499      qualified developers who show an interest and sustained
1500      involvement with your project and try and shift responsibility
1501      towards them.</emphasis> The following ideas might be good places
1502      to start or good sources of inspiration:
1503     </para>
1504  
1505     <sect4>
1506      <title>Allow a larger group of people to have write access to your CVS
1507      repository and make real efforts towards rule by a
1508      committee</title>
1509
1510      <para>
1511       <ulink url="http://httpd.apache.org/">Apache</ulink> is an
1512       example of a project that is run by small group of developers
1513       who vote on major technical issues and the admission of new
1514       members and all have write access to the main source
1515       repository. Their process is detailed <ulink
1516       url="http://httpd.apache.org/ABOUT_APACHE.html">online.</ulink>
1517      </para>
1518
1519      <para>
1520       The <ulink url="http://www.debian.org/"> Debian Project</ulink>
1521       is an extreme example of rule by committee. At current count,
1522       more than 700 developers have full responsibility for
1523       aspects of the project. All these developers can upload into
1524       the main FTP server, and vote on major issues. Direction for
1525       the project is determined by the project's <ulink
1526       url="http://www.debian.org/social_contract">social
1527       contract</ulink> and a <ulink
1528       url="http://www.debian.org/devel/constitution">constitution</ulink>. To
1529       facilitate this system, there are special teams (i.e. the
1530       install team, the Japanese language team) as well as a technical
1531       committee and a project leader. The leader's main responsibility
1532       is to, <quote>appoint delegates or delegate decisions to the
1533       Technical Committee.</quote>
1534      </para>
1535
1536      <para>
1537       While both of these projects operate on a scale that your
1538       project will not (at least initially), their example is
1539       helpful. Debian's idea of a project leader who can do
1540       <emphasis>nothing</emphasis> but delegate serves as a
1541       caricature of how a project can involve and empower a huge
1542       number of developers and grow to a huge size.
1543      </para>
1544
1545     </sect4>
1546
1547     <sect4 id="releasemanager">
1548      <title>Publicly appoint someone as the release manager for a
1549        specific release</title>
1550
1551      <para>
1552       A release manager is usually responsible for coordinating
1553       testing, enforcing a code freeze, being responsible for
1554       stability and quality control, packaging up the software, and
1555       placing it in the appropriate places to be downloaded.
1556      </para>
1557
1558      <para>
1559       This use of the release manager is a good way to give yourself a
1560       break and to shift the responsibility for accepting and
1561       rejecting patches onto someone else. It is a good way of very
1562       clearly defining a chunk of work on the project as belonging to
1563       a certain person and its a great way of giving yourself room to
1564       breath.
1565      </para>
1566     </sect4>
1567
1568     <sect4 id="delegatebranch">
1569      <title>Delegate control of an entire branch</title>
1570      <para>
1571       If your project chooses to have branches (as described in <xref
1572       linkend="branches">), it might be a good idea to appoint someone
1573       else to be the the head of a branch. If you like focusing your
1574       energy on development releases and the implementation of new
1575       features, hand total control over the stable releases to a
1576       well-suited developer.
1577      </para>
1578
1579      <para>
1580       The author of Linux, Linus Torvalds, came out and crowned Alan
1581       Cox as <quote>the man for stable kernels.</quote> All patches
1582       for stable kernels go to Alan and, if Linus were to be taken
1583       away from work on Linux for any reason, Alan Cox would be more
1584       than suited to fill his role as the acknowledged heir to the
1585       Linux maintainership.
1586      </para>
1587     </sect4>
1588    </sect3> 
1589   </sect2>
1590
1591 <!-- Section2: patching -->
1592
1593   <sect2 id="patching">
1594    <title>Accepting and Rejecting Patches</title>
1595    <para>
1596     This HOWTO has already touched on the fact that as the maintainer
1597     of a free software project, one of your primary and most important
1598     responsibilities will be accepting and rejecting patches submitted
1599     to you by other developers.
1600    </para>
1601
1602    <sect3>
1603     <title>Technical judgment</title>
1604
1605     <para>
1606      In <emphasis>Open Source Development with CVS</emphasis>, Karl
1607      Fogel makes a convincing argument that the most important things
1608      to keep in mind when rejecting or accepting patches are:
1609     </para>
1610
1611     <para>
1612      <itemizedlist>
1613
1614       <listitem>
1615        <para>A firm knowledge of the scope of your program (that's the
1616        <quote>idea</quote> I talked about in <xref linkend="chooseproject">);</para>
1617       </listitem>
1618       
1619       <listitem>
1620        <para>The ability to recognize, facilitate, and direct
1621        <quote>evolution</quote> of your program so that the program
1622        can grow and change and incorporate functionality that was
1623        originally unforeseen;</para>
1624       </listitem>
1625
1626       <listitem>
1627        <para>The necessity to avoid digressions that might expand the
1628        scope of the program too much and result and push the project
1629        towards an early death under its own weight and
1630        unwieldiness.</para>
1631       </listitem>
1632
1633      </itemizedlist>
1634     </para>
1635
1636     <para>
1637      These are the criteria that you as a project maintainer should
1638      take into account each time you receive a patch.
1639     </para>
1640
1641     <para>
1642      Fogel elaborates on this and states the <quote>the
1643      questions to ask yourself when considering whether to implement
1644      (or approve) a change are:</quote>
1645     </para>
1646
1647     <para>
1648      <itemizedlist>
1649
1650       <listitem>
1651        <para>Will it benefit a significant percentage of the program's
1652        user community?</para>
1653       </listitem>
1654
1655       <listitem>
1656        <para>Does it fit within the program's domain or within a
1657        natural, intuitive extension of that domain?</para>
1658       </listitem>
1659
1660      </itemizedlist>
1661     </para>
1662
1663     <para>
1664      The answers to these questions are never straightforward and its
1665      very possible (and even likely) that the person who submitted the
1666      patch may feel differently about the answer to these questions
1667      than you do. However, if you feel that that the answer to either
1668      of those questions is <quote>no,</quote> it is your responsibility
1669      to reject the change. If you fail to do this, the project will
1670      become unwieldy and unmaintainable and many ultimately fail.
1671     </para>
1672    </sect3>
1673
1674    <sect3>
1675     <title>Rejecting patches</title>
1676
1677     <para>
1678      Rejecting patches is probably the most difficult and sensitive
1679      job that the maintainer of any free software project has to
1680      face. But sometimes it has to be done. I mentioned earlier (in
1681      <xref linkend="developers"> and in <xref linkend="delegation">)
1682      that you need to try and balance your responsibility and power to
1683      make what you think are the best technical decisions with the
1684      fact that you will lose support from other developers if you seem
1685      like you are on a power trip or being overly bossy or possessive
1686      of the community's project. I recommend that you keep these three
1687      major concepts in mind when rejecting patches (or other changes):
1688     </para>
1689
1690     <sect4>
1691      <title>Bring it to the community</title>
1692      <para>
1693       One of the best ways of justifying a decision to reject a patch
1694       and working to not seem like you keep an iron grip on your
1695       project is by not making the decision alone at all. It might
1696       make sense to turn over larger proposed changes or more
1697       difficult decisions to a development mailing list where they can
1698       be discussed and debated. There will be some patches (bug fixes,
1699       etc.) which will definitely be accepted and some that you feel
1700       are so offbase that they do not even merit further
1701       discussion. It is those that fall into the grey area between
1702       these two groups that might merit a quick forward to a mailing
1703       list.
1704      </para>
1705
1706      <para>
1707       I recommend this process wholeheartedly. As the project
1708       maintainer you are worried about making the best decision for
1709       the project, for the project's users and developers, and for
1710       yourself as a responsible project leader. Turning things over to
1711       an email list will demonstrate your own responsibility and
1712       responsive leadership as it tests and serves the interests of
1713       your software's community.
1714      </para>
1715     </sect4>
1716
1717     <sect4>
1718      <title>Technical issues are not always good justification</title>
1719      <para>
1720       Especially towards the beginning of your project's life, you
1721       will find that many changes are difficult to implement,
1722       introduce new bugs, or have other technical problems. Try to see
1723       past these. Especially with added functionality, good ideas do
1724       not always come from good programmers. Technical merit is a
1725       valid reason to postpone an application of a patch but it is not
1726       always a good reason to reject a change outright. Even small
1727       changes are worth the effort of working with the developer
1728       submitting the patch to iron out bugs and incorporate the change
1729       if you think it seems like a good addition to your project. The
1730       effort on your part will work to make your project a community
1731       project and it will pull a new or less experienced developer
1732       into your project and even teach them something that might help
1733       them in making their next patch.
1734      </para>
1735     </sect4>
1736
1737     <sect4>
1738      <title>Common courtesy</title>
1739      <para>
1740       It should go without saying but, <emphasis>above all and in all
1741       cases, just be nice.</emphasis> If someone has an idea and cares
1742       about it enough to write some code and submit a patch, they
1743       care, they are motivated, and they are already involved. Your
1744       goal as the maintainer is make sure they submit again. They may
1745       have thrown you a dud this time but next time may be the idea or
1746       feature that revolutionizes your project. 
1747      </para>
1748
1749      <para>
1750       It is your responsibility to first justify your choice to not
1751       incorporate their change clearly and concisely. Then thank
1752       them. Let them know that you a appreciate their help and feel
1753       horrible that you can't incorporate their change. Let them know
1754       that you look forward to their staying involved and you hope
1755       that the next patch or idea meshes better with your project
1756       because you appreciate their work and want to see it in your
1757       application. If you have ever had a patch rejected after putting
1758       a large deal of time, thought, and energy into it, you remember
1759       how it feels and it feels bad. Keep this in mind when you have
1760       to let someone down. It's never easy but you need to do
1761       everything you can to make it as not-unpleasant as possible.
1762      </para>
1763     </sect4>
1764    </sect3>
1765   </sect2>
1766
1767 <!-- Section2: branches  -->
1768
1769   <sect2 id="branches">
1770    <title>Stable and Development Branches</title>
1771
1772    <para>
1773     The idea of stable and development branches has already been
1774     described briefly in <xref linkend="chooseversioning"> and in
1775     <xref linkend="delegatebranch">. These allusions attest to some of
1776     the ways that multiple branches can affect your software. Branches
1777     can let you avoid (to some extent) some of the problems around
1778     rejecting patches (as described in <xref linkend="patching">) by
1779     allowing you to temporarily compromise the stability of your
1780     project without affecting those users who need that stability.
1781    </para>
1782
1783    <para>
1784     The most common way of branching your project is to have one
1785     branch that is stable and one that is for development. This is the
1786     model followed by the Linux kernel that is described in <xref
1787     linkend="chooseversioning">. In this model, there is
1788     <emphasis>always</emphasis> one branch that is stable and always
1789     one that is in development. Before any new release, the
1790     development branch goes into a <quote>feature freeze</quote> as
1791     described in <xref linkend="freezing"> where major changes and
1792     added features are rejected or put on hold under the development
1793     kernel is released as the new stable branch and major development
1794     resumes on the development branch. Bug fixes and small changes
1795     that are unlikely to have any large negative repercussions are
1796     incorporated into the stable branch as well as the development
1797     branch.
1798    </para>
1799
1800    <para>
1801     Linux's model provides an extreme example. On many projects, there is no
1802     need to have two versions constantly available. It may make sense to
1803     have two versions only near a release. The Debian project has
1804     historically made both a stable and an unstable distribution
1805     available but has expanded to this to include: stable, unstable,
1806     testing, experimental, and (around release time) a frozen
1807     distribution that only incorporates bug fixes during the
1808     transition from unstable to stable. There are few projects whose
1809     size would necessitate a system like Debian's but this use of
1810     branches helps demonstrate how they can be used to balance
1811     consistent and effective development with the need to make regular
1812     and usable releases.
1813    </para>
1814
1815    <para>
1816     In trying to set up a development tree for yourself, there are
1817     several things that might be useful to keep in mind:
1818    </para>
1819
1820    <para>
1821     <variablelist>
1822
1823      <varlistentry>
1824       <term>Minimize the number of branches</term>
1825       <listitem>
1826        <para>Debian may be able to make good use of four or five
1827        branches but it contains gigabytes of software in over 5000
1828        packages compiled for 5-6 different architectures. For you,
1829        two is probably a good ceiling. Too many branches will confuse
1830        your users (I can't count how many times I had to describe
1831        Debian's system when it only had 2 and sometimes 3 branches!),
1832        potential developers and even yourself. Branches can help but
1833        they come at a cost so use them very sparingly.</para>
1834       </listitem>
1835      </varlistentry>
1836
1837      <varlistentry>
1838       <term>Make sure that all your different branches are explained</term>
1839       <listitem>
1840        <para>As I mentioned in the preceding paragraph, different
1841        branches <emphasis>will</emphasis> confuse your users. Do
1842        everything you can to avoid this by clearly explaining the
1843        different branches in a prominent page on your website and in a
1844        README file in the <acronym>FTP</acronym> or
1845        web directory.</para>
1846
1847        <para>
1848         I might also recommend against a mistake that I think Debian
1849         has made. The terms <quote>unstable,</quote>
1850         <quote>testing,</quote> and <quote>experimental</quote> are
1851         vague and difficult to rank in order of stability (or
1852         instability as the case may be). Try explaining to someone
1853         that <quote>stable</quote> actually means <quote>ultra
1854         stable</quote> and that <quote>unstable</quote> doesn't
1855         actually include any unstable software but is really stable
1856         software that is untested as a distribution.
1857        </para>
1858
1859        <para>
1860         If you are going to use branches, especially early on, keep in
1861         mind that people are conditioned to understand the terms
1862         <quote>stable</quote> and <quote>development</quote> and you
1863         probably can't go wrong with this simple and common division of
1864         branches.
1865        </para>
1866       </listitem>
1867      </varlistentry>
1868
1869      <varlistentry>
1870       <term>Make sure all your branches are always available</term>
1871       <listitem>
1872        <para>Like a lot of this document, this should probably should
1873        go without saying but experience has taught me that it's not
1874        always obvious to people. It's a good idea to physically split
1875        up different branches into different directories or directory
1876        trees on your <acronym>FTP</acronym> or web site. Linux
1877        accomplishes this by having kernels in a v2.2 and a v2.3
1878        subdirectory where it is immediately obvious (after you know
1879        their version numbering scheme) which directory is for the most
1880        recent stable and the current development releases. Debian
1881        accomplishes this by naming all their distribution with names
1882        (i.e. woody, potato, etc.) and then changing symlinks named
1883        <quote>stable,</quote> <quote>unstable</quote> and
1884        <quote>frozen</quote> to point to which ever distribution (by
1885        name) is in whatever stage. Both methods work and there are
1886        others. In any case, it is important that different branches
1887        are always available, are accessible from consistent locations,
1888        and that different branches are clearly distinguished from each
1889        other so your users know exactly what they want and where to
1890        get it.</para>
1891       </listitem>
1892      </varlistentry>
1893
1894     </variablelist>
1895    </para>
1896
1897   </sect2>
1898
1899 <!-- Section2: otherdev -->
1900
1901   <sect2 id="otherdev">
1902    <title>Other Project Management issues</title>
1903    <para>
1904     There are more issues surrounding interaction with developers in a
1905     free software project that I can not touch on in great detail in a
1906     HOWTO of this size and scope. Please don't hesitate to contact me if you see
1907     any major omissions.
1908    </para>
1909
1910    <para>
1911      Other smaller issues that are worth mentioning are:
1912    </para>
1913
1914    <sect3 id="freezing">
1915     <title>Freezing</title>
1916     <para>
1917      For those projects that choose to adopt a split development model
1918      (<xref linkend="branches">), freezing is a concept that is worth
1919      becoming familiar with. 
1920     </para>
1921
1922     <para>
1923      Freezes come in two major forms. A <quote>feature freeze</quote>
1924      is a period when no significant functionality is added to a
1925      program. It is a period where established functionality (even
1926      skeletons of barely working functionality) can be improved and
1927      perfected. It is a period where bugs are fixed. This type of
1928      freeze is usually applied some period (a month or two) before a
1929      release. It is easy to push a release back as you wait for
1930      <quote>one more feature</quote> and a freeze helps to avoid this
1931      situation by drawing the much needed line in the sand. It gives
1932      developers room they need to get a program ready for release.
1933     </para>
1934
1935     <para>
1936      The second type of freeze is a <quote>code freeze</quote> which
1937      is much more like a released piece of software. Once a piece of
1938      software has entered a <quote>code freeze,</quote> all changes to
1939      the code are discouraged and only changes that fix known bugs
1940      are permitted. This type of freeze usually follows a
1941      <quote>feature freeze</quote> and directly precedes a
1942      release. Most released software is in what could be interpreted
1943      as a sort of high level <quote>code freeze.</quote>
1944     </para>
1945
1946     <para>
1947      Even if you never choose to appoint a release manager (<xref
1948      linkend="releasemanager">), you will have an easier time
1949      justifying the rejection or postponement of patches (<xref
1950      linkend="patching">) before a release with a publicly stated
1951      freeze in effect.
1952     </para>
1953    </sect3>
1954   </sect2>
1955
1956    <sect2>
1957     <title>Forks</title>
1958     <para>
1959      I wasn't sure about how I would deal with forking in this
1960      document (or if I would deal with forking at all). A fork is when
1961      a group of developers takes code from a free software project and
1962      actually starts a brand new free software project with it. The
1963      most famous example of a fork was between Emacs and XEmacs. Both
1964      emacsen are based on an identical code-base but for technical,
1965      political, and philosophical reasons, development was split into
1966      two projects which now compete with each other.
1967     </para>
1968
1969     <para>
1970      The short version of the fork section is, <emphasis>don't do
1971      them.</emphasis> Forks force developers to choose one project to
1972      work with, cause nasty political divisions, and redundancy of
1973      work.  Luckily, usually the threat of the fork is enough to scare
1974      the maintainer or maintainers of a project into changing the way
1975      they run their project.
1976     </para>
1977
1978     <para>
1979      In his chapter on <quote>The Open Source Process,</quote> Karl
1980      Fogel describes how to do a fork if you absolutely must. If you
1981      have determined that is absolutely necessary and that the
1982      differences between you and the people threatening to fork are
1983      absolutely unresolvable, I recommend Fogel's book as a good place
1984      to start.
1985     </para>
1986   </sect2>
1987  </sect1>
1988
1989 <!-- Section1: users -->
1990
1991  <sect1 id="users">
1992   <title>Maintaining a Project: Interacting with Users</title>
1993   <indexterm>
1994    <primary>fswd!users</primary>
1995   </indexterm>
1996
1997   <para>
1998    If you've worked your way up to here, congratulations, you are
1999    nearing the end of this document. This final section describes some
2000    of the situations in which you, in your capacity as project
2001    maintainer, will be interacting with users. It gives some
2002    suggestions on how these situations might be handled effectively.
2003   </para>
2004
2005   <para>
2006    Interacting with users is difficult. In our discussion of
2007    interaction with developers, the underlying assumption is that in a
2008    free software project, a project maintainer must constantly strive to
2009    attract and keep developers who can easily leave at any time.
2010   </para>
2011
2012   <para>
2013    Users in the free software community are different than developers
2014    and are also different than users in the world of proprietary
2015    software and they should be treated differently than either
2016    group. Some ways in which the groups differ significantly follow:
2017   </para>
2018
2019   <para>
2020    <itemizedlist>
2021
2022     <listitem>
2023      <para>The lines between users and developers are blurred in ways
2024      that is totally foreign to any proprietary development
2025      model. Your users are often your developers and vice
2026      versa.</para>
2027     </listitem>
2028
2029     <listitem>
2030      <para>In the free software world, you are often your users' only
2031      choice. Because there is such an emphasis on not replicating the
2032      work of others in the free software community and because the
2033      element of competition present in the propriety software model is
2034      absent (or at least in an extremely different form) in the free
2035      software development model, you will probably be the only project
2036      that does what you do (or at least the only one that does what
2037      you do in the way that you do it). This means your responsiveness
2038      to your users is even more important than in the proprietary
2039      software world.</para>
2040     </listitem>
2041
2042     <listitem>
2043      <para>In an almost paradoxical situation, free software projects
2044      have less immediate or dire consequences for ignoring their users
2045      altogether. It is also often easier to do. Because you don't
2046      usually need to compete with another product, chances are good
2047      that you will not be scrambling to gain the features of your
2048      competitor's newest program. This means that your development
2049      process will have to be directed either internally, by a
2050      commitment to your users, or through both.</para>
2051     </listitem>
2052    </itemizedlist>
2053   </para>
2054
2055   <para>
2056    Trying to tackle this unique situation can only be done
2057    indirectly. Developers and maintainers need to listen to users and
2058    to try and be as responsive as possible. A solid knowledge of the
2059    situation recounted above is any free software developer's best tool
2060    for shifting his development or leadership style to fit the unique
2061    process of free software project management. This chapters will try and
2062    introduce some of the more difficult or important points in any
2063    projects interactions with users and give some hints on how to
2064    tackle these.
2065   </para>
2066
2067 <!-- Section2: testing -->
2068
2069   <sect2 id="testing">
2070    <title>Testing and Testers</title>
2071
2072    <para>
2073     In addition to your users being your developers, they are also
2074     (and perhaps more commonly) your testers. Before I get flamed, I
2075     should rephrase my sentence: <emphasis>some of your
2076     users</emphasis> (those who explicityly volunteer) are your
2077     testers.
2078    </para>
2079
2080    <para>
2081     It is important that this distinction be made early on because not
2082     all of your users want to be testers. Many users want to use
2083     stable software and don't care if they don't have the newest,
2084     greatest software with the latest, greatest features. These users
2085     except a stable, tested piece of software without major or obvious
2086     bugs and will be angry if they find themselves testing. This is
2087     yet another way in which a split development model (as mentioned
2088     in <xref linkend="branches">) might come in handy.
2089    </para>
2090
2091    <para>
2092      <quote><ulink
2093      url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
2094      Projects the Open Source Way</ulink></quote> describes what a
2095      good test should look for:
2096    </para>
2097
2098    <variablelist>
2099     <varlistentry>
2100      <term>Boundary conditions</term>
2101
2102      <listitem>
2103       <para>Maximum buffer lengths, data conversions, upper/lower
2104       boundary limits, and so on.</para>
2105      </listitem>
2106
2107     </varlistentry>
2108     <varlistentry>
2109      <term>Inappropriate behavior</term>
2110
2111      <listitem>
2112       <para>Its a good idea to find out what a program will do if a
2113       user hands it a value it isn't expecting, hits the wrong button,
2114       etc. Ask yourself a bunch of <quote>what if</quote> questions
2115       and think of anything that <emphasis>might</emphasis> fail or
2116       <emphasis>might</emphasis> go wrong and find out what your
2117       program would do in those cases.</para>
2118      </listitem>
2119
2120     </varlistentry>
2121     <varlistentry>
2122      <term>Graceful failure</term>
2123
2124      <listitem>
2125       <para>The answer to a number of the <quote>what if</quote>
2126       questions above is probably <quote>failure</quote> which is
2127       often the only answer. Now make sure that it happens
2128       nicely. Make sure that when it crashes, there is some indication
2129       of why it crashed or failed so that the user or developer
2130       understands whats going on.</para>
2131      </listitem>
2132
2133     </varlistentry>
2134
2135     <varlistentry>
2136      <term>Standards conformance</term>
2137
2138      <listitem>
2139       <para>If possible, make sure your programs conforms to
2140       standards. If it's interactive, don't be too creative with
2141       interfaces. If it is non-interactive, make sure it communicates
2142       over appropriate and established channels with other programs
2143       and with the rest of the system.</para>
2144      </listitem>
2145
2146     </varlistentry>
2147    </variablelist>
2148
2149    <sect3>
2150     <title>Automated testing</title>
2151     <para>
2152      For many programs, many common mistakes can be caught by
2153      automated means. Automated tests tend to be pretty good at
2154      catching errors that you've run into several times before or
2155      the things you just forget. They are not very good at finding
2156      errors, even major ones, that are totally unforeseen.
2157     </para>
2158
2159     <para>
2160      CVS comes with a bourne shell script called sanity.sh that is
2161      worth looking at. Debian uses a program called lintian that
2162      checks Debian packages for all of the most common errors. While
2163      use of these scripts may not be helpful, there is a host of other
2164      sanity checking software on the net that may be applicable (feel
2165      free to email me any recommendations). None of these will create
2166      a bug-free release but they will avoid at least some major
2167      oversights. Finally, if your programs become a long term
2168      endeavor, you will find that there are certain errors that you
2169      tend to make over and over. Start a collection of scripts that
2170      check for these errors to help keep them out of future releases.
2171     </para>
2172    </sect3>
2173
2174    <sect3>
2175     <title>Testing by testers</title>
2176     <para>
2177      For any program that depends on user interactivity, many bugs
2178      will only be uncovered through testing by users actually clicking
2179      the keys and pressing the mouse buttons. For this you need
2180      testers and as many as possible.
2181     </para>
2182
2183     <para>
2184      The most difficult part of testing is finding testers. It's
2185      usually a good tactic to post a message to a relevant mailing
2186      list or news group announcing a specific proposed release date
2187      and outlining the functionality of your program. If you put some
2188      time into the announcement, you are sure to get a few responses.
2189     </para>
2190
2191     <para>
2192      The second most difficult part of testing is
2193      <emphasis>keeping</emphasis> your testers and keeping them
2194      actively involved in the testing process. Fortunately, there are
2195      some tried and true tactics that can applied towards this end:
2196     </para>
2197
2198     <para>
2199      <variablelist>
2200
2201       <varlistentry>
2202        <term>Make things simple for your testers</term>
2203        <listitem>
2204         <para>Your testers are doing you a favor so make it as easy as
2205         possible for them. This means that you should be careful to
2206         package your software in a way that is easy to find, unpack,
2207         install, and uninstall. This also means you should explain
2208         what you are looking for to each tester and make the means for
2209         reporting bugs simple and well established. The key is to
2210         provide as much structure as possible to make your testers'
2211         jobs easy and to maintain as much flexibility as possible for
2212         those that want to do things a little differently.</para>
2213        </listitem>
2214       </varlistentry>
2215
2216       <varlistentry>
2217        <term>Be responsive to your testers</term>
2218        <listitem>
2219         <para>When your testers submit bugs, respond to them and
2220         respond quickly. Even if you are only responding to tell them
2221         that the bug has already been fixed, quick and consistent
2222         responses make them feel like their work is heard, important,
2223         and appreciated.</para>
2224        </listitem>
2225       </varlistentry>
2226
2227       <varlistentry>
2228        <term>Thank your testers</term>
2229        <listitem>
2230         <para>Thank them personally each time they send you
2231         patch. Thank them publicly in the documentation and the about
2232         section of your program. You appreciate your testers and your
2233         program would not be possible without their help. Make sure
2234         they know it. Publicly, pat them on the back to make sure the rest of
2235         the world knows it too. It will be appreciated more than you
2236         expected.</para>
2237        </listitem>
2238
2239       </varlistentry>
2240      </variablelist>
2241     </para>
2242
2243    </sect3>
2244   </sect2>
2245
2246 <!-- Section2: support  -->
2247
2248   <sect2 id="support">
2249    <title>Setting up Support Infrastructure</title>
2250
2251    <para>
2252     While testing is important, the large part of your interactions
2253     and responsibility to your users falls under the category of
2254     support. The best way to make sure your users are adequately
2255     supported in using your program is to set up a good infrastructure
2256     for this purpose so that your developers and users help each other
2257     and less of the burden falls on you. This way, people will also
2258     get quicker and better responses to their questions. This
2259     infrastructure comes in several major forms:
2260    </para>
2261
2262    <sect3>
2263     <title>Documentation</title>
2264     <para>
2265      It should not come as any surprise that the key element to any
2266      support infrastructure is good documentation. This topic was
2267      largely covered in <xref linkend="documentation"> and will not be
2268      repeated here.
2269     </para>
2270    </sect3>
2271
2272    <sect3>
2273     <title>Mailing lists</title>
2274     <para>
2275      Aside from documentation, effective mailing lists will be your
2276      greatest tool in providing user support. Running a mailing list
2277      well is more complicated than installing mailing list software
2278      onto a machine.
2279     </para>
2280
2281     <sect4>
2282      <title>Separate lists</title>
2283      
2284      <para>
2285       A good idea is too separate your user and development mailing
2286       lists (perhaps into project-user@host and project-devel@host)
2287       and enforce the division. If people post a development question
2288       onto -user, politely ask them to repost it onto -devel and vise
2289       versa. Subscribe yourself to both groups and encourage all
2290       primarily developers to do the same.
2291      </para>
2292
2293      <para>
2294       This system provides so that no one person is stuck doing all of
2295       the support work and works so that users learn more about the
2296       program, they can help newer users with their questions.
2297      </para>
2298     </sect4>
2299
2300     <sect4>
2301      <title>Choose mailing list software well</title>
2302      <para>
2303       Please don't make the selection of mailing list software
2304       impulsively. Please consider easy accessibility by users without
2305       a lot of technical experience so you want to be as easy as
2306       possible. Web accessibility to an archive of the list is also
2307       important.
2308      </para>
2309
2310      <para>
2311       The two biggest free software mailing list programs are <ulink
2312       url="http://www.greatcircle.com/majordomo/">majordomo</ulink>
2313       and <ulink url="http://www.list.org/">GNU Mailman</ulink>. A
2314       long time advocate of majordomo, I would now recommend any
2315       project choose GNU Mailman. It fulfills the criteria listed
2316       above and makes it easier. It provides a good mailing
2317       list program for a free software project maintainer as opposed
2318       to a good mailing list application for a mailing list
2319       administrator.
2320      </para>
2321
2322      <para>
2323       There are other things you want to take into consideration in
2324       setting up your list. If it is possible to gate your mailing
2325       lists to USENET and provide it in digest form as well as
2326       making them accessible on the web, you will please some users
2327       and work to make the support infrastructure slightly more
2328       accessible.
2329      </para>
2330     </sect4>
2331    </sect3>
2332
2333    <sect3>
2334     <title>Other support ideas</title>
2335
2336     <para>
2337      A mailing list and accessible documentation are far from all you
2338      can do to set up good user support infrastructure. Be
2339      creative. If you stumble across something that works well, email me
2340      and I'll include it here.
2341     </para>
2342
2343     <sect4>
2344      <title>Make your self accessible</title>
2345      <para>
2346       You can not list too few methods to reach you. If you hang out
2347       in an <acronym>IRC</acronym> channel, don't hesitate to list it
2348       in your projects documentation. List email and snailmail
2349       addresses, and ways to reach you via <acronym>ICQ</acronym>,
2350       <acronym>AIM</acronym>, or Jabber if they apply.
2351     </para>
2352     </sect4>
2353
2354     <sect4>
2355      <title>Bug management software</title>
2356      <para>
2357       For many large software projects, use of bug management software
2358       is essential to keep track of which bugs have been fixed, which
2359       bugs have not been fixed, and which bugs are being fixed by
2360       which people. Debian uses the <ulink
2361       url="http://bugs.debian.org">Debian Bug Tracking System</ulink>
2362       (<acronym>BTS</acronym>) although it may not be best choice for
2363       every project (it seems to currently be buckling under its own
2364       weight) As well as a damn good web browser, the mozilla project
2365       has spawned a sub-project resulting in a bug tracking system
2366       called <ulink
2367       url="http://www.mozilla.org/projects/bugzilla/">bugzilla</ulink>
2368       which has become extremely possible and which I like a lot.
2369      </para>
2370
2371      <para>
2372       These systems (and others like them) can be unwieldy so
2373       developers should be careful to not spend more time on the bug
2374       tracking system than on the bugs or the projects themselves. If
2375       a project continues to grow, use of a bug tracking system can
2376       provide an easy standard avenue for users and testers to report
2377       bugs and for developers and maintainers to fix them and track
2378       them in an orderly fashion.
2379      </para>
2380     </sect4>
2381    </sect3>
2382   </sect2>
2383
2384 <!-- Section2: releasing -->
2385
2386   <sect2 id="releasing">
2387    <title>Releasing Your Program</title>
2388
2389    <para>
2390     As mentioned earlier in the HOWTO, the first rule of releasing is,
2391     <emphasis>release something useful.</emphasis> Non-working or
2392     not-useful software will not attract anyone to your
2393     project. People will be turned off of your project and will be likely
2394     to simply gloss over it next time they see a new version
2395     announced. Half-working software, if useful, will intrigue people,
2396     whet their appetites for versions to come, and encourage them to
2397     join the development process.
2398    </para>
2399
2400    <sect3>
2401     <title>When to release</title>
2402
2403     <para>
2404      Making the decision to release your software for the first time
2405      is an incredibly important and incredibly stressful decision. But
2406      it needs to  done. My advice is to try and make something that
2407      is complete enough to be usable and incomplete enough to allow
2408      for flexibility and room for imagination by your future
2409      developers. It's not an easy decision. Ask for help on a local
2410      Linux User Group mailing list or from a group of developer
2411      friends.
2412     </para>
2413
2414     <para>
2415      One tactic is to first do an <quote>alpha</quote> or
2416      <quote>beta</quote> release as described below in <xref
2417      linkend="alphabeta">. However, most of the guidelines described
2418      above still apply.
2419     </para>
2420
2421     <para>
2422      <emphasis>When you feel in your gut that it is time and you feel
2423      you've weighed the situation well several times, cross your
2424      fingers and take the plunge.</emphasis>
2425    </para>
2426
2427     <para>
2428      After you've released for the first time, knowing when to release
2429      becomes less stressful, but just as difficult to gauge. I like
2430      the criteria offered by Robert Krawitz in his article, <ulink
2431      url="http://www.advogato.org/article/196.html"><quote>Free
2432      Software Project Management</quote></ulink> for maintaining a
2433      good release cycle. He recommends that you ask yourself,
2434      <quote>does this release...</quote>
2435     </para>
2436
2437     <para>
2438      <itemizedlist>
2439       <listitem>
2440        <para>Contain sufficient new functionality or bug fixes to be
2441        worth the effort.</para>
2442       </listitem>
2443
2444       <listitem>
2445        <para>Be spaced sufficiently far apart to allow the user time
2446        to work with the latest release.</para>
2447       </listitem>
2448
2449       <listitem>
2450        <para>Be sufficiently functional so that the user can get work
2451        done (quality).</para>
2452       </listitem>
2453      </itemizedlist>
2454     </para>
2455
2456     <para>
2457      If the answer is yes to all of these questions, its probably time
2458      for a release. If in doubt, remember that asking for advice can't
2459      hurt.
2460     </para>
2461    </sect3>
2462
2463    <sect3>
2464     <title>How to release</title>
2465
2466     <para>
2467      If you've followed the guidelines described in this HOWTO up
2468      until this point, the mechanics of doing a release are going to
2469      be the easy part of releasing. If you have set up consistent
2470      distribution locations and the other infrastructure described in
2471      the preceding sections, releasing should be as simple as building
2472      the package, checking it once over, and uploading it into the
2473      appropriate place and then making your website reflect the
2474      change.
2475     </para>
2476    </sect3>
2477
2478    <sect3 id="alphabeta">
2479     <title>Alpha, beta, and development releases</title>
2480
2481     <para>
2482      When contemplating releases, it worth considering the fact that
2483      not every release needs to be a full numbered release. Software
2484      users are accustomed to pre-releases but you must be careful to
2485      label these releases accurately or they will cause more problems then
2486      they are worth.
2487     </para>
2488
2489     <para>
2490      The observation is often made that many free software developers
2491      seem to be confused about the release cycle. <quote><ulink
2492      url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
2493      Projects the Open Source Way</ulink></quote> suggests that you memorize
2494      the phrase, <quote>Alpha is not Beta. Beta is not Release</quote>
2495      and I'd agree that tis is a probably a good idea.
2496     </para>
2497
2498     <para>
2499      <variablelist>
2500
2501       <varlistentry>
2502        <term>alpha releases</term>
2503        <listitem>
2504         <para>Alpha software is feature-complete but sometimes only
2505         partially functional.</para>
2506
2507         <para>Alpha releases are expected to be unstable, perhaps a
2508         little unsafe, but definitely usable. They
2509         <emphasis>can</emphasis> have known bugs and kinks that have
2510         yet to be worked out. Before releasing an alpha, be sure to
2511         keep in mind that <emphasis>alpha releases are still
2512         releases</emphasis> and people are not going to be expecting a
2513         nightly build from the CVS source. An alpha should work and
2514         have minimal testing and bug fixing already finished.</para>
2515        </listitem>
2516       </varlistentry>
2517
2518       <varlistentry>
2519        <term>beta releases</term>
2520        <listitem>
2521         <para>Beta software is feature-complete and functional, but is
2522         in the testing cycle and still has a few bugs left to be
2523         ironed out.</para>
2524
2525         <para>Beta releases are general expected to be usable and
2526         slightly unstable, although definitely <emphasis>not
2527         unsafe.</emphasis> Beta releases usually preclude a full
2528         release by under a month. They can contain small known bugs
2529         but no major ones. All major functionality should be fully
2530         implemented although the exact mechanics can still be worked
2531         out. Beta releases are great tool to whet the appetites of
2532         potential users by giving them a very realistic view of where
2533         your project is going to be in the very near future and can
2534         help keep interest by giving people
2535         <emphasis>something.</emphasis></para>
2536        </listitem>
2537       </varlistentry>
2538
2539       <varlistentry>
2540        <term>development releases</term>
2541        <listitem>
2542         <para><quote>Development release</quote> is much a more vague
2543         term than <quote>alpha</quote> or <quote>beta</quote>. I
2544         usually choose to reserve the term for discussion of a
2545         development branch although there are other ways to use the
2546         term. So many in fact, that I feel the term has been
2547         cheapened. The popular window manager <ulink
2548         url="http://www.enlightenment.org">Enlightenment</ulink> has
2549         released <emphasis>nothing but</emphasis> development
2550         releases. Most often, the term is used to describe releases
2551         that are not even alpha or beta and if I were to release a
2552         pre-alpha version of a piece of software in order to keep
2553         interest in my project alive, this is probably how I would
2554         have to label it.</para>
2555        </listitem>
2556       </varlistentry>
2557
2558      </variablelist>
2559
2560     </para>
2561    </sect3>
2562   </sect2>
2563
2564 <!-- Section2: announcing  -->
2565
2566   <sect2 id="announcing">
2567    <title>Announcing Your Project</title>
2568
2569    <para>
2570     Well, you've done it. You've (at least for the purposes of this
2571     HOWTO) designed, built, and released your free software
2572     project. All that is left is for you to tell the world so they
2573     know to come and try it out and hopefully jump on board with
2574     development. If everything is in order as described above, this
2575     will be a quick and painless process. A quick announcement is all
2576     that it takes to put yourself on the free software community's
2577     radar screen.
2578    </para>
2579
2580    <sect3>
2581     <title>Mailing lists and USENET</title>
2582     <para>
2583      Email is still the way that most people on the Internet get their
2584      information. Its a good idea to send a message announcing your
2585      program to any relevant mailing list you know of and any relevant
2586      USENET discussion group. Karl Fogel recommends that use you
2587      simple subject describing the fact that the message is an
2588      announcement, the name of the program, the version, and a
2589      half-line long description of its functionality. This way, any
2590      interested user or developer will be immediately attracted to
2591      your announcement. Fogel's example looks like:
2592     </para>
2593
2594     <screen>Subject: ANN: aub 1.0, a program to assemble USENET binaries</screen>
2595
2596     <para>
2597      The rest of the email should describe the programs functionality
2598      quickly and concisely in no more than two paragraphs and should
2599      provide links to the projects webpage and direct links to
2600      downloads for those that want to try it right away.
2601     </para>
2602
2603     <para>
2604      You should repeat this announcement process consistently in the
2605      same locations for each subsequent release.
2606     </para>
2607    </sect3>
2608
2609    <sect3>
2610     <title>freshmeat.net</title>
2611     <para>
2612      Mentioned earlier in <xref linkend="evalwhere">, in today's free
2613      software community, announcements of your project on freshmeat
2614      are almost more important than announcements on mailing lists.
2615     </para>
2616
2617     <para>
2618      Visit the <ulink url="http://freshmeat.net">freshmeat.net
2619      website</ulink> or their <ulink
2620      url="http://freshmeat.net/add-project/">submit project
2621      page</ulink> to post your project onto their site and into their
2622      database. In addition to a large website, freshmeat provides a
2623      daily newsletter that highlights all the days releases and
2624      reaches a huge audience (I personally skim it every night for any
2625      interesting new releases).
2626     </para>
2627    </sect3>
2628   </sect2>
2629 </sect1>
2630
2631  <bibliography>
2632
2633   <bibliodiv>
2634    <title>Printed Books</title>
2635
2636    <biblioentry>
2637     <biblioset>
2638      <author>
2639       <surname>Fogel</surname>
2640       <firstname>Karl</firstname>
2641      </author>
2642      
2643      <title>Open Source Development with CVS</title>
2644      
2645      <publisher>
2646       <publishername>Coriolois Open Press</publishername>
2647      </publisher>
2648      <pubdate>1999</pubdate>
2649
2650      <isbn>1-57610-490-7</isbn>
2651
2652      <abstract>
2653       <para>
2654        Fogel's <quote>guide to using CVS in the free software
2655        world</quote> is much more than its subitle. In the publisher's
2656        own words: <quote><emphasis>Open Source Development with
2657        CVS</emphasis> is one of the first books available that teaches
2658        you development and implementation of Open Source
2659        software.</quote> It also includes the best reference and
2660        tutorial to CVS I have ever seen. It is the book that was
2661        <emphasis>so good</emphasis> that it prompted me to write this
2662        HOWTO because I thought the role it tried to serve was so
2663        important and useful. Please check it or buy it if you can and
2664        are seriously interested in running a free software project.
2665       </para>
2666      </abstract>
2667     </biblioset>
2668    </biblioentry>
2669
2670    <biblioentry
2671     <biblioset>
2672      <author>
2673       <surname>Lessig</surname>
2674       <firstname>Lawrence</firstname>
2675      </author>
2676
2677      <title>Code and Other Laws of Cyberspace</title>
2678      
2679      <publisher>
2680       <publishername>Basic Books</publishername>
2681      </publisher>
2682      <pubdate>2000</pubdate>
2683      
2684      <isbn>0-465-03913-8</isbn>
2685
2686      <abstract>
2687       <para>
2688        While it only briefly talks about free software (and does it by
2689        tiptoeing around the free software/open source issue with the
2690        spineless use of the term <quote>open code</quote> that only a
2691        laywer could coin), Lessig's book is brilliant. Written by a
2692        lawyer, it talks about how regulation on the Internet is not
2693        done with law, but with the code itself and how the nature of
2694        the code will determine the nature of future freedoms. In
2695        addition to being a quick and enjoyable read, it gives some
2696        cool history and describes how we <emphasis>need</emphasis>
2697        free software in a way more powerfully than anything I've read
2698        outside of <ulink
2699        url="http://www.gnu.org/philosophy/right-to-read.html">RMS's
2700        <quote>Right to Read.</quote></ulink>
2701       </para>
2702      </abstract>
2703     </biblioset>
2704    </biblioentry>
2705    
2706    <biblioentry>
2707     <biblioset>
2708      <author>
2709       <surname>Raymond</surname>
2710       <firstname>Eric</firstname>
2711      </author>
2712      
2713      <title>The Cathedral and the Bazaar</title>
2714      <subtitle>Musings on Linux and Open Source by an Accidental Revolutionary</subtitle>
2715      
2716      <publisher>
2717       <publishername>O'Reilly</publishername>
2718      </publisher>
2719      <pubdate>1999</pubdate>
2720     
2721      <isbn>1-56592-724-9</isbn>
2722      <abstract>
2723       <para>
2724        Although I have to honestly say that I am not the ESR fan that
2725        I used to be, this book proved invaluable in getting me where I
2726        am today. The essay that gives the book its title does a good
2727        job of sketching the free software process and does an an
2728        amazing job of making an argument for free software/open source
2729        development as a road to better software. The rest of the book
2730        has other of ESR's articles, which for the most part are posted
2731        on his website. Still, it's nice thing to own in hard copy and
2732        something that every free software/open source hacker should
2733        read.
2734       </para>
2735      </abstract>
2736     </biblioset>
2737    </biblioentry>
2738   </bibliodiv>
2739
2740   <bibliodiv>
2741    <title>Web-Accessable Resources</title>
2742
2743    <para>
2744     This is a list of the web resources pertaining to this HOWTO that
2745     I've found most helpful in compiling this information. If you know
2746     of others that would help, please don't hesitate to email me at
2747     <email>mako@debian.org</email> and we can look into getting it
2748     added to the list and represented in the HOWTO.
2749    </para>
2750
2751    <para>
2752     I'd recommend that any free software developer (or potential one)
2753     skim through these sites becaue they have each have a lot to say.
2754    </para>
2755
2756    <biblioentry>
2757     <biblioset>
2758      <author>
2759       <surname>Manley</surname>
2760       <firstname>Montey</firstname>
2761      </author>
2762      
2763      <title><ulink
2764      url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
2765      Projects the Open Source Way</ulink></title>
2766      
2767      <publisher>
2768       <publishername><ulink
2769       url="http://www.linuxprogramming.com">Linux
2770       Programming</ulink></publishername>
2771      </publisher>
2772      <pubdate>Oct 31, 2000</pubdate>
2773
2774      <abstract>
2775       <para>
2776        In one of the better articles on the subject that I've read,
2777        Monty sums up some of the major points I touch on including:
2778        starting a project, testing, documenation, organizing a team and
2779        leadership, and several other topics. While more opiniated that
2780        I try to be, I think its an important article that I found very
2781        helpful in writing this HOWTO. I've tried to cite him in
2782        the places where I borrowed from him most.
2783       </para>
2784
2785       <para>
2786        I have problems much of this piece and I recommend you read
2787        <xref linkend="krawitz"> at the same time you read Monty's
2788        article for a good critique.
2789       </para>
2790      </abstract>
2791     </biblioset>
2792    </biblioentry>
2793
2794    <biblioentry>
2795     <biblioset>
2796      <author>
2797       <surname>Gabriel</surname>
2798       <firstname>Richard</firstname>
2799      </author>
2800      
2801      <title><ulink
2802      url="http://www.jwz.org/doc/worse-is-better.html">The Rise of
2803      <quote>Worse is Better</quote></ulink></title>
2804
2805      <abstract>
2806       <para>
2807        A well written article although I think the title may have
2808        confused as many people as the rest of the essay helped. It
2809        offers a good description of how to design programs that will
2810        succeed and stay maintainable as they grow.
2811       </para>
2812      </abstract>
2813     </biblioset>
2814    </biblioentry>
2815   </bibliodiv>
2816
2817   <bibliodiv>
2818    <title>Advogato Articles</title>
2819
2820    <para>
2821     I've found that one of the best resources that any free software
2822     developer has at his or her disposal is Advogato.org. If you haven't
2823     yet had a chance to visit <ulink url="http://www.advogato.org">the
2824     website</ulink>, do.
2825    </para>
2826
2827    <para>
2828     I have spent a huge amount of time on advogato and I've gone
2829     through and provided links to the articles that I think might be
2830     of particular interest to anyone reading this HOWTO. I think that
2831     skimming through these links can be helfpul and I promise that if
2832     you do, you'll learn a lot. You will learn that my idea of how a
2833     free software project should be run is not the
2834     <emphasis>only</emphasis> idea. I think that's important.
2835    </para>
2836
2837    <para>
2838     If nothing else, there is <emphasis>way</emphasis> more
2839     information on that website than I could ever fit into, or
2840     reference from this HOWTO. I have listed what I think are the most
2841     relavant articles here with short descriptions that I've written.
2842    </para>
2843
2844
2845    <biblioentry>
2846     <biblioset>
2847      <author>
2848       <surname>Hindle</surname>
2849       <firstname>Stephen</firstname>
2850      </author>
2851      
2852      <title><ulink url="http://www.advogato.org/article/262.html">'Best Practices' for Open Source?</ulink></title>
2853      
2854      <publisher>
2855       <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
2856      </publisher>
2857      <pubdate>March 21, 2001</pubdate>
2858
2859      <abstract>
2860       <para>
2861        Touching mostly on programming practice (as most articles on
2862        the subject usually do), the article talks a little about
2863        project managment (<quote>Use it!</quote>) and a bit about
2864        communication within a free software project.
2865       </para>
2866      </abstract>
2867     </biblioset>
2868    </biblioentry>
2869
2870    <biblioentry>
2871     <biblioset>
2872      <author>
2873       <surname>Cohen</surname>
2874       <firstname>Bram</firstname>
2875      </author>
2876      
2877      <title><ulink
2878      url="http://www.advogato.org/article/258.html"></ulink>How to
2879      Write Maintainable Code</title>
2880      
2881      <publisher>
2882       <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
2883      </publisher>
2884      <pubdate>March 15, 2001</pubdate>
2885      
2886      <abstract>
2887       <para>
2888        This article touches upon the "writing maintainable code"
2889        discussion that I try hard to avoid in my HOWTO. It's one of
2890        the better (and most diplomatic) articles on the subject that
2891        I've found.
2892       </para>
2893      </abstract>
2894     </biblioset>
2895    </biblioentry>
2896    <biblioentry id="krawitz">
2897     <biblioset>
2898      <author>
2899       <surname>Krawitz</surname>
2900       <firstname>Robert</firstname>
2901      </author>
2902      
2903      <title><ulink url="http://www.advogato.org/article/196.html">Free
2904      Source Project Management</ulink></title>
2905      
2906      <publisher>
2907       <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
2908      </publisher>
2909      <pubdate>November 4, 2000</pubdate>
2910     
2911      <abstract>
2912       <para>
2913        This article made me happy because it challenged many of the
2914        problems that I had with Monty's article on <ulink
2915        url="http://www.linuxprogramming.com">LinuxProgramming</ulink>. The
2916        author argues that Monty calls simply for the application of
2917        old (proprietary software) project management techniques in
2918        free software projects instead of working to come up with
2919        something new. I found his article to be extremely well thought
2920        out and I think it's an essential read for any free software
2921        project manager.
2922       </para>
2923      </abstract>
2924     </biblioset>
2925    </biblioentry>
2926
2927    <biblioentry>
2928     <biblioset>
2929      <author>
2930       <surname>Martins</surname>
2931       <firstname>Lalo</firstname>
2932      </author>
2933      
2934      <title><ulink url="http://www.advogato.org/article/128.html">Ask
2935      the Advogatos: why do Free Software projects
2936      fail?</ulink></title>
2937      
2938      <publisher>
2939       <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
2940      </publisher>
2941      <pubdate>July 20, 2000</pubdate>
2942
2943      <abstract>
2944       <para>
2945        While the article is little more than a question, reading the
2946        answers to this question offered by advogato's readers can
2947        help. In a lot of ways, this HOWTO acts as my answer to the
2948        questions posed in this article but there are others, many of
2949        which might take issue with whats is in this HOWTO. It's worth
2950        checking out.
2951       </para>
2952      </abstract>
2953     </biblioset>
2954    </biblioentry>
2955
2956    <biblioentry>
2957     <biblioset>
2958      <author>
2959       <surname>Burley</surname>
2960       <firstname>David</firstname>
2961      </author>
2962      
2963      <title><ulink
2964      url="http://www.advogato.org/article/107.html">In-Roads to Free
2965      Software Development</ulink></title>
2966      
2967      <publisher>
2968       <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
2969      </publisher>
2970      <pubdate>June 14, 2000</pubdate>
2971     
2972      <abstract>
2973       <para>
2974        This document was written as a response to <ulink
2975        url="http://www.advogato.org/article/72.html">another advogato
2976        article</ulink>. Although not about running a project, this
2977        describes some of the ways that you can get started with free
2978        software development without starting a project. I think this
2979        is an important article. If you are interested in becoming
2980        involved with free software, this article showcases some of the
2981        ways that you can do this without actually starting a project
2982        (something that I hope this HOWTO has demonstrated is not to be
2983        taken lightly).
2984       </para>
2985      </abstract>
2986     </biblioset>
2987    </biblioentry>
2988
2989    <biblioentry>
2990     <biblioset>
2991      <author>
2992       <surname>Moorman</surname>
2993       <firstname>Jacob</firstname>
2994      </author>
2995      
2996      <title><ulink
2997      url="http://www.advogato.org/article/72.html"></ulink>Importance
2998      of Non-Developer Supporters in Free Software</title>
2999      
3000      <publisher>
3001       <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
3002      </publisher>
3003      <pubdate>April 16, 2000</pubdate>
3004     
3005      <abstract>
3006       <para>
3007        Moorman's is a short article but it brings up some good
3008        points. The comment reminding developers to thank their testers
3009        and end-users is invaluable and oft-forgotten.
3010       </para>
3011      </abstract>
3012     </biblioset>
3013    </biblioentry>
3014
3015    <biblioentry>
3016     <biblioset>
3017      <author>
3018       <surname>Orchard</surname>
3019       <firstname>Leslie</firstname>
3020      </author>
3021      
3022      <title><ulink url="http://www.advogato.org/article/67.html">On
3023      Naming an Open Source Project</ulink></title>
3024      
3025      <publisher>
3026       <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
3027      </publisher>
3028      <pubdate>April 12, 2000</pubdate>
3029     
3030      <abstract>
3031       <para>
3032        I didn't even have a section on project naming in this HOWTO
3033        (See <xref linkend="naming">) until Leslie Orchard's article
3034        reminded me of it. Thanks to Leslie for writing this article!
3035       </para>
3036      </abstract>
3037     </biblioset>
3038    </biblioentry>
3039
3040    <biblioentry>
3041     <biblioset>
3042      <author>
3043       <surname>Allen</surname>
3044       <firstname>David</firstname>
3045      </author>
3046      
3047      <title><ulink url="http://www.advogato.org/article/40.html">Version Numbering Madness</ulink></title>
3048      
3049      <publisher>
3050       <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
3051      </publisher>
3052      <pubdate>Februrary 28, 2000</pubdate>
3053     
3054      <abstract>
3055       <para>
3056        In this article, David Allen challengs the whole
3057        <quote>Major.Minor.Patch</quote> version numbering scheme. Its
3058        good to read this as you read <xref
3059        linkend="chooseversioning">. I liked the article and it
3060        describes some of the projects that I bring up in my discussion
3061        of verion numbering.
3062       </para>
3063      </abstract>
3064     </biblioset>
3065    </biblioentry>
3066
3067   </bibliodiv>
3068  </bibliography>
3069
3070 <!--  
3071      The GNU Free Documentation License 1.1 in DocBook
3072      Markup by Eric Baudais <baudais@okstate.edu>
3073      Maintained by the GNOME Documentation Project
3074      http://developer.gnome.org/projects/gdp
3075      Version: 1.0.1
3076      Last Modified: Nov 16, 2000
3077 -->
3078
3079 <appendix id="fdl">
3080   <docinfo>
3081     <releaseinfo>
3082       Version 1.1, March 2000
3083     </releaseinfo>
3084     <copyright>
3085       <year>2000</year><holder>Free Software Foundation, Inc.</holder>
3086     </copyright>
3087     <legalnotice id="fdl-legalnotice">
3088       <para>
3089         <address>Free Software Foundation, Inc. <street>59 Temple Place, 
3090         Suite 330</street>, <city>Boston</city>, <state>MA</state>  
3091         <postcode>02111-1307</postcode>  <country>USA</country></address> 
3092         Everyone is permitted to copy and distribute verbatim copies of this 
3093         license document, but changing it is not allowed.
3094       </para>
3095     </legalnotice>
3096   </docinfo>
3097   <title>GNU Free Documentation License</title>
3098
3099   <sect1 id="fdl-preamble">
3100     <title>0. PREAMBLE</title>
3101     <para>
3102       The purpose of this License is to make a manual, textbook, or
3103       other written document <quote>free</quote> in the sense of
3104       freedom: to assure everyone the effective freedom to copy and
3105       redistribute it, with or without modifying it, either
3106       commercially or noncommercially. Secondarily, this License
3107       preserves for the author and publisher a way to get credit for
3108       their work, while not being considered responsible for
3109       modifications made by others.
3110     </para>
3111     
3112     <para>
3113       This License is a kind of <quote>copyleft</quote>, which means
3114       that derivative works of the document must themselves be free in
3115       the same sense. It complements the GNU General Public License,
3116       which is a copyleft license designed for free software.
3117     </para>
3118     
3119     <para>
3120       We have designed this License in order to use it for manuals for
3121       free software, because free software needs free documentation: a
3122       free program should come with manuals providing the same
3123       freedoms that the software does. But this License is not limited
3124       to software manuals; it can be used for any textual work,
3125       regardless of subject matter or whether it is published as a
3126       printed book. We recommend this License principally for works
3127       whose purpose is instruction or reference.
3128     </para>
3129   </sect1>
3130   <sect1 id="fdl-section1">
3131     <title>1. APPLICABILITY AND DEFINITIONS</title>
3132     <para id="fdl-document">
3133       This License applies to any manual or other work that contains a
3134       notice placed by the copyright holder saying it can be
3135       distributed under the terms of this License. The
3136       <quote>Document</quote>, below, refers to any such manual or
3137       work. Any member of the public is a licensee, and is addressed
3138       as <quote>you</quote>.
3139     </para>
3140     
3141     <para id="fdl-modified">
3142       A <quote>Modified Version</quote> of the Document means any work
3143       containing the Document or a portion of it, either copied
3144       verbatim, or with modifications and/or translated into another
3145       language.
3146     </para>
3147         
3148     <para id="fdl-secondary">
3149       A <quote>Secondary Section</quote> is a named appendix or a
3150       front-matter section of the <link
3151       linkend="fdl-document">Document</link> that deals exclusively
3152       with the relationship of the publishers or authors of the
3153       Document to the Document's overall subject (or to related
3154       matters) and contains nothing that could fall directly within
3155       that overall subject. (For example, if the Document is in part a
3156       textbook of mathematics, a Secondary Section may not explain any
3157       mathematics.)  The relationship could be a matter of historical
3158       connection with the subject or with related matters, or of
3159       legal, commercial, philosophical, ethical or political position
3160       regarding them.
3161     </para>
3162
3163     <para id="fdl-invariant">
3164       The <quote>Invariant Sections</quote> are certain <link
3165       linkend="fdl-secondary"> Secondary Sections</link> whose titles
3166       are designated, as being those of Invariant Sections, in the
3167       notice that says that the <link
3168       linkend="fdl-document">Document</link> is released under this
3169       License.
3170     </para>
3171     
3172     <para id="fdl-cover-texts">
3173       The <quote>Cover Texts</quote> are certain short passages of
3174       text that are listed, as Front-Cover Texts or Back-Cover Texts,
3175       in the notice that says that the <link
3176       linkend="fdl-document">Document</link> is released under this
3177       License.
3178     </para>
3179         
3180     <para id="fdl-transparent">
3181       A <quote>Transparent</quote> copy of the <link
3182       linkend="fdl-document"> Document</link> means a machine-readable
3183       copy, represented in a format whose specification is available
3184       to the general public, whose contents can be viewed and edited
3185       directly and straightforwardly with generic text editors or (for
3186       images composed of pixels) generic paint programs or (for
3187       drawings) some widely available drawing editor, and that is
3188       suitable for input to text formatters or for automatic
3189       translation to a variety of formats suitable for input to text
3190       formatters. A copy made in an otherwise Transparent file format
3191       whose markup has been designed to thwart or discourage
3192       subsequent modification by readers is not Transparent.  A copy
3193       that is not <quote>Transparent</quote> is called
3194       <quote>Opaque</quote>.
3195     </para>
3196     
3197     <para>
3198       Examples of suitable formats for Transparent copies include
3199       plain ASCII without markup, Texinfo input format, LaTeX input
3200       format, SGML or XML using a publicly available DTD, and
3201       standard-conforming simple HTML designed for human
3202       modification. Opaque formats include PostScript, PDF,
3203       proprietary formats that can be read and edited only by
3204       proprietary word processors, SGML or XML for which the DTD
3205       and/or processing tools are not generally available, and the
3206       machine-generated HTML produced by some word processors for
3207       output purposes only.
3208     </para>
3209     
3210     <para id="fdl-title-page">
3211       The <quote>Title Page</quote> means, for a printed book, the
3212       title page itself, plus such following pages as are needed to
3213       hold, legibly, the material this License requires to appear in
3214       the title page. For works in formats which do not have any title
3215       page as such, <quote>Title Page</quote> means the text near the
3216       most prominent appearance of the work's title, preceding the
3217       beginning of the body of the text.
3218     </para>
3219   </sect1>
3220     
3221   <sect1 id="fdl-section2">
3222     <title>2. VERBATIM COPYING</title>
3223     <para>
3224       You may copy and distribute the <link
3225       linkend="fdl-document">Document</link> in any medium, either
3226       commercially or noncommercially, provided that this License, the
3227       copyright notices, and the license notice saying this License
3228       applies to the Document are reproduced in all copies, and that
3229       you add no other conditions whatsoever to those of this
3230       License. You may not use technical measures to obstruct or
3231       control the reading or further copying of the copies you make or
3232       distribute. However, you may accept compensation in exchange for
3233       copies. If you distribute a large enough number of copies you
3234       must also follow the conditions in <link
3235       linkend="fdl-section3">section 3</link>.
3236     </para>
3237     
3238     <para>
3239       You may also lend copies, under the same conditions stated
3240       above, and you may publicly display copies.
3241     </para>
3242     </sect1>
3243     
3244   <sect1 id="fdl-section3">
3245     <title>3. COPYING IN QUANTITY</title>
3246     <para>
3247       If you publish printed copies of the <link
3248       linkend="fdl-document">Document</link> numbering more than 100,
3249       and the Document's license notice requires <link
3250       linkend="fdl-cover-texts">Cover Texts</link>, you must enclose
3251       the copies in covers that carry, clearly and legibly, all these
3252       Cover Texts: Front-Cover Texts on the front cover, and
3253       Back-Cover Texts on the back cover. Both covers must also
3254       clearly and legibly identify you as the publisher of these
3255       copies. The front cover must present the full title with all
3256       words of the title equally prominent and visible. You may add
3257       other material on the covers in addition. Copying with changes
3258       limited to the covers, as long as they preserve the title of the
3259       <link linkend="fdl-document">Document</link> and satisfy these
3260       conditions, can be treated as verbatim copying in other
3261       respects.
3262     </para>
3263     
3264     <para>
3265       If the required texts for either cover are too voluminous to fit
3266       legibly, you should put the first ones listed (as many as fit
3267       reasonably) on the actual cover, and continue the rest onto
3268       adjacent pages.
3269     </para>
3270     
3271     <para>
3272       If you publish or distribute <link
3273       linkend="fdl-transparent">Opaque</link> copies of the <link
3274       linkend="fdl-document">Document</link> numbering more than 100,
3275       you must either include a machine-readable <link
3276       linkend="fdl-transparent">Transparent</link> copy along with
3277       each Opaque copy, or state in or with each Opaque copy a
3278       publicly-accessible computer-network location containing a
3279       complete Transparent copy of the Document, free of added
3280       material, which the general network-using public has access to
3281       download anonymously at no charge using public-standard network
3282       protocols. If you use the latter option, you must take
3283       reasonably prudent steps, when you begin distribution of Opaque
3284       copies in quantity, to ensure that this Transparent copy will
3285       remain thus accessible at the stated location until at least one
3286       year after the last time you distribute an Opaque copy (directly
3287       or through your agents or retailers) of that edition to the
3288       public.
3289     </para>
3290     
3291     <para>
3292       It is requested, but not required, that you contact the authors
3293       of the <link linkend="fdl-document">Document</link> well before
3294       redistributing any large number of copies, to give them a chance
3295       to provide you with an updated version of the Document.
3296     </para>
3297     </sect1>
3298     
3299   <sect1 id="fdl-section4">
3300     <title>4. MODIFICATIONS</title>
3301     <para>
3302       You may copy and distribute a <link
3303       linkend="fdl-modified">Modified Version</link> of the <link
3304       linkend="fdl-document">Document</link> under the conditions of
3305       sections <link linkend="fdl-section2">2</link> and <link
3306       linkend="fdl-section3">3</link> above, provided that you release
3307       the Modified Version under precisely this License, with the
3308       Modified Version filling the role of the Document, thus
3309       licensing distribution and modification of the Modified Version
3310       to whoever possesses a copy of it. In addition, you must do
3311       these things in the Modified Version:
3312     </para>
3313     
3314     <itemizedlist mark="opencircle">
3315       <listitem>
3316         <formalpara>
3317           <title>A</title>
3318           <para>
3319             Use in the <link linkend="fdl-title-page">Title
3320             Page</link> (and on the covers, if any) a title distinct
3321             from that of the <link
3322             linkend="fdl-document">Document</link>, and from those of
3323             previous versions (which should, if there were any, be
3324             listed in the History section of the Document). You may
3325             use the same title as a previous version if the original
3326             publisher of that version gives permission.
3327           </para>
3328         </formalpara>
3329       </listitem>
3330       
3331       <listitem>
3332         <formalpara>
3333           <title>B</title>
3334           <para>
3335             List on the <link linkend="fdl-title-page">Title
3336             Page</link>, as authors, one or more persons or entities
3337             responsible for authorship of the modifications in the
3338             <link linkend="fdl-modified">Modified Version</link>,
3339             together with at least five of the principal authors of
3340             the <link linkend="fdl-document">Document</link> (all of
3341             its principal authors, if it has less than five).
3342           </para>
3343         </formalpara>
3344       </listitem>
3345       
3346       <listitem>
3347         <formalpara>
3348           <title>C</title>
3349           <para>
3350             State on the <link linkend="fdl-title-page">Title
3351             Page</link> the name of the publisher of the <link
3352             linkend="fdl-modified">Modified Version</link>, as the
3353             publisher.
3354           </para>
3355         </formalpara>
3356       </listitem>
3357       
3358       <listitem>
3359         <formalpara>
3360           <title>D</title>
3361           <para>
3362             Preserve all the copyright notices of the <link
3363             linkend="fdl-document">Document</link>.
3364           </para>
3365         </formalpara>
3366       </listitem>
3367       
3368       <listitem>
3369         <formalpara>
3370           <title>E</title>
3371           <para>
3372             Add an appropriate copyright notice for your modifications
3373             adjacent to the other copyright notices.
3374           </para>
3375         </formalpara>
3376       </listitem>
3377       
3378       <listitem>
3379         <formalpara>
3380           <title>F</title>
3381           <para>
3382             Include, immediately after the copyright notices, a
3383             license notice giving the public permission to use the
3384             <link linkend="fdl-modified">Modified Version</link> under
3385             the terms of this License, in the form shown in the
3386             Addendum below.
3387           </para>
3388         </formalpara>
3389       </listitem>
3390       
3391       <listitem>
3392         <formalpara>
3393           <title>G</title>
3394           <para>
3395             Preserve in that license notice the full lists of <link
3396             linkend="fdl-invariant"> Invariant Sections</link> and
3397             required <link linkend="fdl-cover-texts">Cover
3398             Texts</link> given in the <link
3399             linkend="fdl-document">Document's</link> license notice.
3400           </para>
3401         </formalpara>
3402       </listitem>
3403       
3404       <listitem>
3405         <formalpara>
3406           <title>H</title>
3407           <para>
3408             Include an unaltered copy of this License.
3409           </para>
3410         </formalpara>
3411       </listitem>
3412       
3413       <listitem>
3414         <formalpara>
3415           <title>I</title>
3416           <para>
3417             Preserve the section entitled <quote>History</quote>, and
3418             its title, and add to it an item stating at least the
3419             title, year, new authors, and publisher of the <link
3420             linkend="fdl-modified">Modified Version </link>as given on
3421             the <link linkend="fdl-title-page">Title Page</link>.  If
3422             there is no section entitled <quote>History</quote> in the
3423             <link linkend="fdl-document">Document</link>, create one
3424             stating the title, year, authors, and publisher of the
3425             Document as given on its Title Page, then add an item
3426             describing the Modified Version as stated in the previous
3427             sentence.
3428           </para>
3429         </formalpara>
3430       </listitem>
3431       
3432       <listitem>
3433         <formalpara>
3434           <title>J</title>
3435           <para>
3436             Preserve the network location, if any, given in the <link
3437             linkend="fdl-document">Document</link> for public access
3438             to a <link linkend="fdl-transparent">Transparent</link>
3439             copy of the Document, and likewise the network locations
3440             given in the Document for previous versions it was based
3441             on. These may be placed in the <quote>History</quote>
3442             section.  You may omit a network location for a work that
3443             was published at least four years before the Document
3444             itself, or if the original publisher of the version it
3445             refers to gives permission.
3446           </para>
3447         </formalpara>
3448       </listitem>
3449       
3450       <listitem>
3451         <formalpara>
3452           <title>K</title>
3453           <para>
3454             In any section entitled <quote>Acknowledgements</quote> or
3455             <quote>Dedications</quote>, preserve the section's title,
3456             and preserve in the section all the substance and tone of
3457             each of the contributor acknowledgements and/or
3458             dedications given therein.
3459           </para>
3460         </formalpara>
3461       </listitem>
3462       
3463       <listitem>
3464         <formalpara>
3465           <title>L</title>
3466           <para>
3467             Preserve all the <link linkend="fdl-invariant">Invariant
3468             Sections</link> of the <link
3469             linkend="fdl-document">Document</link>, unaltered in their
3470             text and in their titles.  Section numbers or the
3471             equivalent are not considered part of the section titles.
3472           </para>
3473         </formalpara>
3474       </listitem>
3475       
3476       <listitem>
3477         <formalpara>
3478           <title>M</title>
3479           <para>
3480             Delete any section entitled
3481             <quote>Endorsements</quote>. Such a section may not be
3482             included in the <link linkend="fdl-modified">Modified
3483             Version</link>.
3484           </para>
3485         </formalpara>
3486       </listitem>
3487       
3488       <listitem>
3489         <formalpara>
3490           <title>N</title>
3491           <para>
3492             Do not retitle any existing section as
3493             <quote>Endorsements</quote> or to conflict in title with
3494             any <link linkend="fdl-invariant">Invariant
3495             Section</link>.
3496           </para>
3497         </formalpara>
3498       </listitem>
3499     </itemizedlist>
3500     
3501     <para>
3502       If the <link linkend="fdl-modified">Modified Version</link>
3503       includes new front-matter sections or appendices that qualify as
3504       <link linkend="fdl-secondary">Secondary Sections</link> and
3505       contain no material copied from the Document, you may at your
3506       option designate some or all of these sections as invariant. To
3507       do this, add their titles to the list of <link
3508       linkend="fdl-invariant">Invariant Sections</link> in the
3509       Modified Version's license notice.  These titles must be
3510       distinct from any other section titles.
3511     </para>
3512     
3513     <para>
3514       You may add a section entitled <quote>Endorsements</quote>,
3515       provided it contains nothing but endorsements of your <link
3516       linkend="fdl-modified">Modified Version</link> by various
3517       parties--for example, statements of peer review or that the text
3518       has been approved by an organization as the authoritative
3519       definition of a standard.
3520     </para>
3521     
3522     <para>
3523       You may add a passage of up to five words as a <link
3524       linkend="fdl-cover-texts">Front-Cover Text</link>, and a passage
3525       of up to 25 words as a <link
3526       linkend="fdl-cover-texts">Back-Cover Text</link>, to the end of
3527       the list of <link linkend="fdl-cover-texts">Cover Texts</link>
3528       in the <link linkend="fdl-modified">Modified Version</link>.
3529       Only one passage of Front-Cover Text and one of Back-Cover Text
3530       may be added by (or through arrangements made by) any one
3531       entity. If the <link linkend="fdl-document">Document</link>
3532       already includes a cover text for the same cover, previously
3533       added by you or by arrangement made by the same entity you are
3534       acting on behalf of, you may not add another; but you may
3535       replace the old one, on explicit permission from the previous
3536       publisher that added the old one.
3537     </para>
3538     
3539     <para>
3540       The author(s) and publisher(s) of the <link
3541       linkend="fdl-document">Document</link> do not by this License
3542       give permission to use their names for publicity for or to
3543       assert or imply endorsement of any <link
3544       linkend="fdl-modified">Modified Version </link>.
3545     </para>
3546   </sect1>
3547     
3548   <sect1 id="fdl-section5">
3549     <title>5. COMBINING DOCUMENTS</title>
3550     <para>
3551       You may combine the <link linkend="fdl-document">Document</link>
3552       with other documents released under this License, under the
3553       terms defined in <link linkend="fdl-section4">section 4</link>
3554       above for modified versions, provided that you include in the
3555       combination all of the <link linkend="fdl-invariant">Invariant
3556       Sections</link> of all of the original documents, unmodified,
3557       and list them all as Invariant Sections of your combined work in
3558       its license notice.
3559     </para>
3560     
3561     <para>
3562       The combined work need only contain one copy of this License,
3563       and multiple identical <link linkend="fdl-invariant">Invariant
3564       Sections</link> may be replaced with a single copy. If there are
3565       multiple Invariant Sections with the same name but different
3566       contents, make the title of each such section unique by adding
3567       at the end of it, in parentheses, the name of the original
3568       author or publisher of that section if known, or else a unique
3569       number. Make the same adjustment to the section titles in the
3570       list of Invariant Sections in the license notice of the combined
3571       work.
3572     </para>
3573     
3574     <para>
3575       In the combination, you must combine any sections entitled
3576       <quote>History</quote> in the various original documents,
3577       forming one section entitled <quote>History</quote>; likewise
3578       combine any sections entitled <quote>Acknowledgements</quote>,
3579       and any sections entitled <quote>Dedications</quote>.  You must
3580       delete all sections entitled <quote>Endorsements.</quote>
3581     </para>
3582     </sect1>
3583     
3584   <sect1 id="fdl-section6">
3585     <title>6. COLLECTIONS OF DOCUMENTS</title>
3586     <para>
3587       You may make a collection consisting of the <link
3588       linkend="fdl-document">Document</link> and other documents
3589       released under this License, and replace the individual copies
3590       of this License in the various documents with a single copy that
3591       is included in the collection, provided that you follow the
3592       rules of this License for verbatim copying of each of the
3593       documents in all other respects.