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