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