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