713938b94825226c8a9a152ff435ee735b36eb4b
[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 Development 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
18         </address>
19      </affiliation>
20   </author>
21
22    <revhistory>
23       <revision>
24          <revnumber>v0.01</revnumber>
25          <date>25 March 2001</date>
26          <authorinitials>bch</authorinitials>
27           <revremark>
28           Initial Release
29          </revremark>
30       </revision>
31    </revhistory>
32
33   <abstract>
34     <indexterm>
35       <primary>fswd</primary>
36     </indexterm>
37
38     <para>
39      This HOWTO is designed for people with experience in programming
40      and some skills in managing a software project but who are new to
41      the world of Free Software. This document is meant to act as a
42      guide to the non-technical aspects of free software development
43      and was written to act as a crash course in the people skills
44      that aren't taught to commercial coders but that can make or
45      break a free software project.
46     </para>
47   </abstract>
48
49  </artheader>
50
51 <!-- Section1: intro -->
52
53  <sect1 id="intro">
54    <title>Introduction</title>
55
56    <indexterm>
57     <primary>fswd!introduction</primary>
58    </indexterm>
59
60   <para>
61    For various reasons, this release has been code-named the
62    <emphasis>homemade yogurt</emphasis> release.
63   </para>
64
65   <para>
66    New code names will appear as per industry standard
67    guidelines to emphasize the state-of-the-art-ness of this
68    document.
69   </para>
70
71   <para>
72    Skimming through freshmeat.net provides mountains of reasons for this
73    HOWTO's existence--the Internet is littered with excellently
74    written and useful programs that have faded away into the Universe
75    of Free Software Forgottenness. This dismal scene made me ask
76    myself, "Why?"
77   </para>
78
79   <para>
80    This HOWTO tries to do a lot of thing (probably too many), but it
81    can't answer that question and won't attempt it. What this HOWTO
82    will attempt to do is give your Free Software project a fighting
83    chance--an edge. If you write a piece of crap that no one is
84    interested in, you can read this HOWTO until you can recite it in
85    your sleep and your project will probably fail. Then again, you can
86    write a beautiful, relevant piece of software and follow every
87    instruction in this HOWTO and your software may still not make
88    it. Sometimes life is like that. However, I'll go out a limb and
89    say that if you write a great, relevant pieces of software and
90    ignore the advise in this HOWTO, you'll probably fail <emphasis>
91    more often</emphasis>.
92   </para>
93
94   <para>
95    A lot of the information in this HOWTO is best called common
96    sense. Of course, as any debate on interfaces will prove, what is
97    common sense to some programmers proves totally unintuitive to
98    others. After explaining bits and pieces of this HOWTO to Free
99    Software developers on several occasions, I realized that writing
100    this HOWTO might provide a useful resource and a forum for
101    programmers to share ideas about what has and has not worked for
102    them.
103   </para>
104
105   <para>
106    As anyone involved in any of what seems like an unending parade of
107    ridiculous intellectual property clashes will attest to, a little
108    bit of legalese proves important.
109   </para>
110
111 <!-- Section2: copyright -->
112
113   <sect2 id="copyright">
114    <title>Copyright Information</title>
115
116    <para>
117     This document is copyrighted (c) 2000 Benjamin (Mako) Hill and is
118     distributed under the terms of the Linux Documentation Project
119     (LDP) license, stated below.
120    </para>
121
122    <para>
123     Unless otherwise stated, Linux HOWTO documents are copyrighted by
124     their respective authors. Linux HOWTO documents may be reproduced
125     and distributed in whole or in part, in any medium physical or
126     electronic, as long as this copyright notice is retained on all
127     copies. Commercial redistribution is allowed and encouraged;
128     however, the author would like to be notified of any such
129     distributions.
130    </para>
131
132    <para>
133     All translations, derivative works, or aggregate works
134     incorporating any Linux HOWTO documents must be covered under this
135     copyright notice. That is, you may not produce a derivative work
136     from a HOWTO and impose additional restrictions on its
137     distribution. Exceptions to these rules may be granted under
138     certain conditions; please contact the Linux HOWTO coordinator at
139     the address given below.
140    </para>
141
142    <para>
143     In short, we wish to promote dissemination of this information
144     through as many channels as possible. However, we do wish to
145     retain copyright on the HOWTO documents, and would like to be
146     notified of any plans to redistribute the HOWTOs.
147    </para>
148
149    <para>
150     If you have any questions, please contact
151     <email>linux-howto@metalab.unc.edu</email>
152    </para>
153   </sect2>
154
155 <!-- Section2: disclaimer -->
156
157   <sect2 id="disclaimer">
158    <title>Disclaimer</title>
159
160    <para>
161     No liability for the contents of this documents can be accepted.
162     Use the concepts, examples and other content at your own risk.  As
163     this is a new edition of this document, there may be errors and
164     inaccuracies, that may of course be damaging to your system.
165     Proceed with caution, and although this is highly unlikely, the
166     author(s) do not take any responsibility for that.
167    </para>
168
169    <para>
170     All copyrights are held by their by their respective owners, unless
171     specifically noted otherwise.  Use of a term in this document
172     should not be regarded as affecting the validity of any trademark
173     or service mark.
174    </para>
175
176    <para>
177     Naming of particular products or brands should not be seen 
178     as endorsements.
179    </para>
180
181    <para>
182     You are strongly recommended to take a backup of your system 
183     before major installation and backups at regular intervals.
184    </para>
185   </sect2>
186
187 <!-- Section2: newversions-->
188
189   <sect2 id="newversions">
190    <title>New Versions</title>
191
192     <indexterm>
193      <primary>fswd!news on</primary>
194     </indexterm>
195
196    <para>
197     This is the initial release. It is written to be released to
198     developers for critique and brainstorming and submitted to
199     Hampshire College for academic credit. Please keep in mind that
200     this version of the HOWTO is still in an infant stage and will be
201     revised extensively before it hits the LDP.
202    </para>
203
204    <para>
205     The latest version number of this document should always be listed
206     on <ulink url="http://people.debian.org/~mako/">my webpage at
207     Debian</ulink>.
208    </para>
209
210    <para>
211     The newest version of this HOWTO will always be made available at
212     the same website, in a variety of formats:
213    </para>
214
215    <para>
216    <itemizedlist>
217     <listitem>
218      <para>
219       <ulink url="http://people.debian.org/~mako/howto/fswd-howto.html">HTML</ulink>.
220      </para>
221     </listitem>
222
223     <listitem>
224      <para>
225        <ulink URL="http://people.debian.org/~mako/howto/fswd-howto.txt">plain text</ulink>.
226      </para>
227     </listitem>
228
229     <listitem>
230      <para>
231       <ulink url="http://people.debian.org/~mako/howto/fswd-howto.US.ps.gz">compressed 
232        postscript (US letter format)</ulink>.
233      </para>
234     </listitem>
235
236     <listitem>
237      <para>
238       <ulink url="http://people.debian.org/~mako/howto/fswd-howto.UF.ps.gz">compressed 
239        postscript (Universal format / 8.27x11in; 210x279mm)</ulink>.
240      </para>
241     </listitem>
242
243     <listitem>
244      <para>
245       <ulink url="http://people.debian.org/~mako/howto/fswd-howto.sgml">SGML source</ulink>.
246      </para>
247     </listitem>
248    </itemizedlist>
249    </para>
250   </sect2>
251
252 <!-- Section2: credits -->
253
254   <sect2 id="credits">
255    <title>Credits</title>
256
257    <para>
258     In this version I have the pleasure of acknowledging:
259    </para>
260
261    <para>
262     <emphasis>Karl Fogel</emphasis>, the author of <emphasis>Open
263     Source Development with CVS</emphasis> published by the Coriolis
264     Open Press. Large parts of the book are available <ulink
265     url="http://cvsbook.red-bean.com">on the web</ulink>. 225 pages of
266     the book are available under the GPL and constitute the best
267     tutorial on CVS I have ever seen. The rest of the book covers,
268     "the challenges and philosophical issues inherent in running an
269     Open Source project using CVS." The book does a good job of
270     covering some of the subjects brought up in this HOWTO and much
271     more. <ulink url="http://cvsbook.red-bean.com">The book's
272     website</ulink> has information on ordering the book and provides
273     several translations of the chapters on CVS. I you are seriously
274     interested in running a Free Software project, you want this
275     book. I tried to mention Fogel in sections of this HOWTO where I
276     knew I was borrowing directly from his ideas. If I missed any, I'm
277     sorry, and I'll try and have those fixed in future versions.
278    </para>
279    
280    <para>
281     Karl Fogel can be reached at <email>kfogel (at) red-bean (dot)
282     com</email>
283    </para>
284    <para>
285     Also providing support material, and inspiration for this HOWTO is
286     Eric S. Raymond for his prolific, consistent, and carefully
287     crafted arguments, Lawrence Lessig for reminding me of the
288     importance of Free Software and finally, every user and developer
289     involved with the <ulink url="http://www.debian.org">Debian
290     Project</ulink>. The project has provided me with a home, a place
291     to practice Free Software advocacy, a place to make a difference,
292     a place to learn from those how have been involved with the
293     movement much longer than I, and proof of a Free Software project
294     that definitely, definitely works.
295    </para>
296
297    <para>
298     Above all, I want to thank <emphasis>Richard Stallman</emphasis>
299     for his work at the Free Software Foundation and for never giving
300     up. Stallman provides and articulates the philosophical basis that
301     attracts me to Free Software and that drives me towards writing a
302     document to make sure it succeeds. RMS can always be emailed at
303     <email>rms (at) gnu (dot) org</email>.
304    </para>
305
306   </sect2>
307
308 <!-- Section2: feedback -->
309
310   <sect2 id="feedback">
311    <title>Feedback</title>
312
313    <para>
314     Feedback is most certainly welcome for this document. Without your
315     submissions and input, this document wouldn't exist. Something
316     missing? Don't hesitate to contact me and to write a chapter or
317     section, or subsection. I want this document to be a product of
318     the Free Software development process that it heralds and I think
319     its ultimate success will be rooted in this fact. Please send your
320     additions, comments and criticisms to the following email address
321     : <email>mako@debian. org</email>.
322    </para>
323    </sect2>
324
325 <!-- Section2: translations -->
326
327   <sect2 id="translations">
328    <title>Translations</title>
329
330    <para>
331     I know that not everyone speaks English. Translations are nice and
332     I'd love for this HOWTO to gain the kind of international reach
333     afforded by a translated version.
334    </para>
335
336    <para>
337     However, this HOWTO is still young and I have to yet to be
338     contacted about a translation so English is all that is currently
339     available. If you would like to help with or do a translation, you
340     will gain my utmost respect and admiration and you'll get to be
341     part of a cool process. If you are at all interested, please don't
342     hesitate to contact me at: <email>mako@debian.org</email>.
343    </para>
344    </sect2>
345  </sect1>
346
347 <!-- Section1: intro: END -->
348
349 <!-- Section1: starting -->
350
351  <sect1 id="starting">
352   <title>Starting a Project</title>
353
354    <indexterm>
355     <primary>fswd!starting</primary>
356    </indexterm>
357   <para>
358    With very little argument, starting a project is most difficult
359    part of successful free software development. Laying a firm
360    foundation for your project will determine whether your project
361    flourishes or withers away and dies. It is also the subject that is
362    of most immediate interest to anyone reading this document as a
363    tutorial.
364   </para>
365
366   <para>
367    Starting a project also involves a dilemma that you as a developer
368    must try and deal with. No potential user for your program will be
369    interested by a program that doesn't work. Simultaneously, the
370    development process that you want to employ holds involvement of
371    users as essential to the process of the development that will
372    realize this working software.
373   </para>
374
375   <para>
376    It is in these dangerous initial moments that anyone working to
377    start a free software project must strike a balance. One of the
378    most important ways that someone trying to start a project can work
379    towards this balance is by establishing a framework for the
380    development process through some of the ways mentioned in this
381    section.
382   </para>
383
384
385 <!-- Section2: chooseproject-->
386
387   <sect2 id="chooseproject">
388    <title>Choosing a Project</title>
389
390    <para>
391     If you are reading this document, there's a good chance you
392     already have an idea for a project in mind. Chances are pretty
393     good, it fills a gap by doing something that no other free
394     software process does or or does it in a way that is unique
395     enough to necessitate a separate project.
396    </para>
397
398    <sect3 id=identifyidea>
399     <title>Identify and articulate your idea</title>
400     <para>
401      Eric S. Raymond writes about how free software projects start in
402      his paper, "The Cathedral and the Bazaar" which comes as required
403      reading for any free software development. You can find it <ulink
404      url="http://www.tuxedo.org/~esr/writings/cathedral-bazaar/">online
405      </ulink>.
406     </para>
407
408     <para>
409      In "The Cathedral and Bazaar," Raymond tells us that:
410      <emphasis>Every good work of software starts by scratching a
411      developers itch.</emphasis> Raymond now widely accepted
412      hypothesis is that new free software programs are written, first
413      and foremost, to solve a specific problem facing the developer.
414     </para>
415
416     <para>
417      If you have an idea for a program in mind, chances are good that
418      it it is targeting a specific problem or itch you want to see
419      scratched. <emphasis>This idea is the project. Articulate it
420      clearly. Write it out. Describe the problem you will attack in
421      detail. The success of your project in tackling a particular
422      problem will be tied to your ability to identify that problem
423      early on. Find out exactly what it is that you want your project
424      to do.</emphasis>
425     </para>
426    </sect3>
427
428    <sect3 id=evalulateidea>
429     <title>Evaluate your idea</title>
430
431     <para>
432      In evaluating your idea, you need to ask yourself questions.
433      Before you move any further into this HOWTO, you need to
434      determine if the free software development model really is the
435      right one for your project. Obviously, since the program
436      scratches your itch, you are definitely interested in seeing it
437      implemented in code. But, because one hacker coding alone fails
438      to qualify as a free software development effort, you need to ask
439      yourself the question: <emphasis>Is anybody else
440      interested?</emphasis>
441     </para>
442
443     <para>
444      Sometimes the answer is <emphasis>no</emphasis>. If you want to
445      write a set of scripts to sort <emphasis>your</emphasis>
446      <acronym>MP3</acronym> collection on your machine, maybe the free
447      software development model is not the best one to
448      choose. However, if you want to write a set of scripts to sort
449      <emphasis>anyone's</emphasis> <acronym>MP3</acronym>s, a free
450      software project might fill a useful gap.
451     </para>
452
453     <para>
454      Luckily, The Internet is a place so big and diverse that, chances
455      are, there is someone, somewhere, who shares your interests and
456      how feels the same itch. It is the fact that there are so many
457      people with so many similar needs and desires that introduces the
458      second major question: <emphasis>Has somebody already had your
459      idea or a reasonably similar one?</emphasis>
460     </para>
461
462      <sect4 id=evalwhere>
463       <title>Finding Similar Projects</title>
464
465      <para>
466       There are places you can go on the web to try and answer this
467       question. If you have experience with the free software
468       community, you are probably already familiar with all of these
469       sites. All of the resources listed bellow offer searching of
470       their databases:
471      </para>
472
473      <para>
474      <variablelist>
475        <varlistentry>
476         <term>freshmeat.net:</term>
477         <listitem>
478          <para><ulink url="http://freshmeat.net">freshmeat</ulink>
479          describes itself as, <quote>the Web's largest index of Linux
480          and Open Source software</quote> and its reputation along
481          these lines remains unquestioned. If you can't find it on
482          freshmeat, its doubtful that you'll find it indexed anywhere
483          else.</para>
484         </listitem>
485        </varlistentry>
486
487        <varlistentry>
488         <term>Slashdot:</term>
489         <listitem>
490          <para><ulink url="http://slashdot.org">Slashdot</ulink>
491          provides <quote>News for Nerds: Stuff that Matters,</quote>
492          which usually includes discussion of free software, open
493          source, technology, and geek culture new and events. It is
494          not unusual for an particularly sexy development effort to be
495          announced here so it definitely worth checking.</para>
496         </listitem>
497        </varlistentry>
498
499        <varlistentry>
500         <term>SourceForge:</term>
501         <listitem>
502          <para><ulink url="http://sourceforge.net">SourceForge</ulink>
503          houses and facilitates a growing number of open source and
504          free software projects, SourceForge is quickly becoming a
505          nexus and an necessary stop for free software
506          developers. SourceForge's <ulink
507          url="http://sourceforge.net/softwaremap/trove_list.php">software
508          map</ulink> and <ulink url="http://sourceforge.net/new/"> new
509          releases</ulink> pages. should be necessary stops before
510          embarking on a new free software project. SourceForge also
511          provides a at <ulink
512          url="http://sourceforge.net/snippet/">Code Snippet
513          Library</ulink> which contains useful reusable chunks of
514          code in an array of languages which can come in useful in any
515          project.</para>
516         </listitem>
517        </varlistentry>
518
519        <varlistentry>
520         <term>Google and Google's Linux Search:</term>
521         <listitem>
522          <para><ulink url="http://www.google.com">Google</ulink> and
523          <ulink url="http://www.google.com/linux"> Google's Linux
524          Search</ulink>, provide powerful web searches that may
525          reveal people working on similar projects. It is not a
526          catalog of software or news like freshmeat or Slashdot, but
527          it is worth checking before you begin pouring your effort
528          into a redundant project.</para>
529         </listitem>
530        </varlistentry>
531
532       </variablelist>
533      </para>
534     </sect4>
535
536     <sect4 id=evalhow>
537      <title>Deciding to Proceed</title>
538      <para>
539       Once you have successful charted the terrain and have an idea
540       bout what kinds of similar free software projects exist, every
541       developer needs to decide whether to proceed with their own
542       project. It is rare that a new project seeks to accomplish a
543       goal that is not similar to related to the goal of another
544       project. Anyone starting a new project needs to ask themselves:
545       <emphasis>Will the new project be duplicating work done by
546       another project? Will the new project be competing for
547       developers with an existing project? Can the goals of the new
548       project be accomplished by adding functionality to an existing
549       project?</emphasis>
550      </para>
551
552      <para>
553       If the answer to any of these questions is yes, try to contact
554       the developer of the existing project in question and see if he
555       or she might be willing to collaborate with you.
556      </para>
557
558      <para>
559       This may be the single most difficult aspect of free software
560       development for many developers but it is essential. It is easy
561       to become fired up by and idea and be caught up in the momentum
562       and excitement of a new project. It is often extremely difficult
563       but it is important that any free software developer remember
564       that the best interests of the of the free software community
565       and the quickest way to accomplish ones own project's goals and
566       the goals of similar project can often be accomplished by
567       <emphasis>not</emphasis> starting a new project.
568      </para>
569
570     </sect4>
571    </sect3>
572   </sect2>
573
574 <!-- Section2: licensing-->
575
576   <sect2 id="licensing">
577    <title>Licensing your Software</title>
578    
579    <para>
580     On one level, the difference between a piece of free software and
581     a piece of propriety software is the license. A license helps both
582     you as the developer by protecting your legal rights to your
583     software and helps demonstrate to those who wish to help you or
584     your project that they are encouraged to join.
585    </para>
586    
587    <sect3 id="chooselicense">
588     <title>Choosing a license</title>
589
590     <para>
591      Any discussion of licenses is also sure to generate at least a
592      small flame war as there are strong feelings that some free
593      software licenses are better than other free software
594      licenses. This discussion also brings up the question of
595      <quote>Open Source Software</quote> and the debate around
596      <quote>Open Source Software</quote> and <quote>Free
597      Software</quote>. However, because I've written the Free Software
598      Development HOWTO and not the Open Source Development HOWTO, my
599      own allegiances in this argument are out in the open.
600     </para>
601
602     <para>
603      In attempting to reach a middle ground, I recommend picking any
604      license that conforms to the <ulink
605      url="http://www.debian.org/social_contract">Debian Free Software
606      Guidelines</ulink>. Examples of these licenses are the
607      <acronym>GPL</acronym>, the <acronym>BSD</acronym>, and the
608      Artistic License. Conforming to the definition of Free Software
609      offered by Richard Stallman in <ulink
610      url="http://www.gnu.org/philosophy/free-sw.html">The Free
611      Software Definition</ulink>, any of these licenses will
612      uphold,<quote> users' freedom to run, copy, distribute, study,
613      change and improve the software.</quote> There are other licenses
614      as well but sticking with a more common license will offer the
615      advantage of immediate recognition and understanding.
616     </para>
617
618     <para>
619      In attempting a more in-depth analysis, I agree with Karl Fogel's
620      description of licenses as falling into two groups: those that
621      are the <acronym>GPL</acronym> and those that are not the
622      <acronym>GPL</acronym>.
623     </para>
624
625     <para>
626      Personally, I license all my software under the
627      <acronym>GPL</acronym>. Created and protected by the Free
628      Software Foundation and the GNU Project, the
629      <acronym>GPL</acronym> is the license for the Linux kernel,
630      GNOME, Emacs, and the majority of Linux software. Its an easy
631      choice but I believe it is a good one. <emphasis>However, there
632      is a viral aspect to the <acronym>GPL</acronym>that prevents the
633      mixture of <acronym>GPL</acronym>'ed code with
634      non-<acronym>GPL</acronym>'ed code. To many people (myself
635      included), this is a benefit, but to some, it is a major
636      drawback.</emphasis>
637     </para>
638
639     <para>
640      The three major license can be found at the following locations:
641     </para>
642
643     <para>
644      <itemizedlist>
645       <listitem>
646        <para><ulink url="http://www.gnu.org/copyleft/gpl.html">The GNU
647        General Public License</ulink></para>
648       </listitem>
649       <listitem>
650        <para><ulink url="http://www.debian.org/misc/bsd.license">The
651        BSD License</ulink></para>
652       </listitem>
653       <listitem>
654        <para><ulink
655        url="http://language.perl.com/misc/Artistic.html">The Artistic
656        License</ulink></para>
657       </listitem>
658      </itemizedlist>
659     </para>
660
661     <para>
662      <emphasis>In all cases, please read through any license before
663      your release your software. As the developer, you can't afford
664      any license surprises.</emphasis>
665     </para>
666    </sect3>
667
668    <sect3 id="licensechoose">
669     <title>The mechanics of licensing</title>
670
671     <para>
672      The text of the <acronym>GPL</acronym> offers <ulink
673      url="http://www.gnu.org/copyleft/gpl.html#SEC4">a good
674      description</ulink> of mechanics of applying a license to a piece
675      of software. A checklist for applying a license would include:
676     </para>
677
678     <para>
679     <orderedlist>
680       <listitem>
681
682        <para>If at all possible, attach and distribute a full copy of
683        the license with the source and binary in a separate
684        file.</para>
685
686       </listitem>
687       <listitem>
688
689        <para>At the top of each source file in your program, attach a
690        notice of copyright and information on where the full license
691        can be found. The <acronym>GPL</acronym> recommends that each
692        file begin with:</para>
693
694        <screen>
695 <emphasis>one line to give the program's name and an idea of what it does.</emphasis>
696 Copyright (C) yyyy  name of author
697
698 This program is free software; you can redistribute it and/or
699 modify it under the terms of the GNU General Public License
700 as published by the Free Software Foundation; either version 2
701 of the License, or (at your option) any later version.
702
703 This program is distributed in the hope that it will be useful,
704 but WITHOUT ANY WARRANTY; without even the implied warranty of
705 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
706 GNU General Public License for more details.
707
708 You should have received a copy of the GNU General Public License
709 along with this program; if not, write to the Free Software
710 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
711        </screen>
712
713        <para>
714         The <acronym>GPL</acronym> goes on to recommend attaching
715         information on contacting you (the author) via email or
716         physical mail.
717       </para>
718
719       </listitem>
720       <listitem>
721
722        <para>
723         The <acronym>GPL</acronym> continues and suggests that if your
724         program runs in an interactive mode, you should have the
725         program output a notice each time it enters interactive mode
726         that includes a message like this one that points to more
727         information about the programs licensing:
728        </para>
729
730        <screen>
731 Gnomovision version 69, Copyright (C) year name of author
732 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
733 type `show w'.  This is free software, and you are welcome
734 to redistribute it under certain conditions; type `show c' 
735 for details.
736        </screen>
737
738       </listitem>
739       <listitem>
740        <para>Finally, it might be helpful to include a
741        <quote>copyright disclaimer</quote> with the program from an
742        employer or a school if you work as a programmer or if it seems
743        like your employer or school might be able to make an argument
744        for ownership of your code.</para>
745       </listitem>
746
747      </orderedlist>
748      </para>    
749    </sect3>
750
751    <sect3 id="licensewarning">
752     <title>Final license warning</title>
753
754     <para>
755      Please, please, please, place your software under some
756      license. It may not seem important, and to you, it may not be,
757      but licenses are important. For a piece of software to be
758      included in the Debian GNU/Linux distribution, it must have a
759      license that fits the <ulink
760      url="http://www.debian.org/social_contract">Debian Free Software
761      Guidelines</ulink>. If you have no license, your program can be
762      distributed in part of Debian until you re-release it under a free
763      license. Please save yourself and others trouble by releasing the
764      first version of your software with a clear license.
765     </para>
766
767    </sect3>
768
769  </sect2>
770
771 <!-- Section2: chooseversioning-->
772
773   <sect2 id="chooseversioning">
774    <title>Choosing a Method of Version Numbering</title>
775    <para>
776     <emphasis>The most important thing about a system of numbering is
777     that there is one.</emphasis> It may seem pedantic to emphasize
778     this point but you'd be surprised at the number of scripts and
779     small programs that pop up without any version number. 
780    </para>
781
782    <para>
783     <emphasis>The second most important thing about a system of
784     numbering is that the numbers always go up.</emphasis> Automatic
785     versioning systems and people's sense of order in the universe
786     will fall apart if version numbers don't rise. It doesn't
787     <emphasis>really</emphasis> matter if 2.1 is a big jump and
788     2.0.005 is a small jump but it does matter that 2.1 is more recent
789     than 2.0.005.
790    </para>
791
792    <para>
793     Follow these two rules and you will not go wrong. Still there are
794     several versioning system that are well known, useful, and that
795     might be worth looking into before you release your first version.
796    </para>
797
798    <variablelist>
799     <varlistentry>
800      <term>Linux kernel version numbering:</term>
801      <listitem>
802       <para>The Linux kernel uses a versioning system where the any
803       minor odd minor version number refers to an development or
804       testing release and any even minor version number refers to a
805       stable version. Under this system, 2.1 and 2.3 kernels were and
806       always will be development and testing kernels and 2.0, 2.2. and
807       2.4 kernels are all production code with a higher degree of
808       stability.
809      </para>
810
811       <para>
812        Whether you plan on having a split development model (as
813        described in <xref linkend="branches">) or only one version
814        released at a time, my experience with several free software
815        projects and with the Debian project has taught me that use of
816        Linux's version numbering system is worth taking into
817        consideration. In Debian, all minor versions are stable
818        distributions (2.0, 2.1, etc). However, many people assume that
819        2.1 is an unstable or development version and continue to use
820        an older version until they get so frustrated with the lack of
821        development and progress that they complain. If you never
822        release an odd minor version but only release even ones, nobody
823        is hurt, and less people are confused.
824       </para>
825
826      </listitem>
827     </varlistentry>
828     <varlistentry>
829      <term>Wine version numbering:</term>
830      <listitem>
831       <para>Because of the unusual nature of wine's development where
832       it constantly improving but not working towards any immediately
833       achievable goal, wine is released every three weeks. Wine does
834       this by versioning their releases in Year Month Day format where
835       each release might be labeled <quote>wine-XXXXXXXX</quote> where
836       the version from January 04, 2000 would be
837       <quote>wine-20000104</quote>. For certain projects, Year Month
838       Day format can make a lot of sense.
839       </para>
840
841      </listitem>
842     </varlistentry>
843     <varlistentry>
844      <term>Mozilla milestones:</term>
845      <listitem>
846       <para>When one considers Netscape 6 and vendor versions, the
847       mozilla's project development structure is one of the most
848       complex free software model available. Their version numbering
849       has reflected the unique situation in which it is
850       developed.
851       </para>
852
853       <para>
854        Mozilla's development structure has historically been made up
855        of milestones. From the beginning of the mozilla project, the
856        goals of the project in the order and degree to which they were
857        to be achieved were charted out on a series of <ulink
858        url="http://www.mozilla.org/roadmap.html">road
859        maps</ulink>. Major points and achievements along this road-maps
860        were marked as milestones. Therefore, mozilla was built and
861        distributed nightly as "nightly builds" but on a day when the
862        goals of a milestone on the road-map had been reached, that
863        particular build was marked as a milestone release.
864       </para>
865
866       <para>
867        While I haven't seen this method employed in any other projects
868        to date, I like the idea and think that it might have value in
869        any testing or development branch of a large free application
870        under heavy development.
871       </para>
872
873      </listitem>
874     </varlistentry>
875    </variablelist>
876   </sect2>
877
878 <!-- Section2: documentation-->
879
880   <sect2 id="documentation">
881    <title>Documentation</title>
882
883    <para>
884     A huge number of otherwise fantastic free software applications
885     have withered because their author was the only person who knew
886     how to use them well. Even if your program is written primarily
887     for a techno-savvy group of users, documentation is helpful and
888     necessary for the survival of your project. You will learn later
889     in <xref linkend="releasing"> that you must always release
890     something that is usable. <emphasis>A piece of software without
891     documentation is not usable.</emphasis>
892    </para>
893
894    <para>
895     There are lots of ways to document your project and lots of
896     different people to document for. The idea of documentation the
897     code itself to help facilitate development by a large community is
898     vital but is outside the scope of this HOWTO. This being the case,
899     this section deals mostly useful tactics for user-directed
900     documentation.
901    </para>
902
903    <para>
904     A combination of tradition and necessity has resulted in a
905     semi-regular system method of documentation in most free software
906     projects that is worth following. Both users and developers expect
907     to be able to get documentation in several ways and its essential
908     that you provide the information they are seeking in a form they
909     can read if your project is ever going to get off the
910     ground. People have come to expect:
911    </para>
912
913    <sect3>
914     <title>Man pages</title> 
915
916     <para>Your users will want to be able to type <quote>man
917     foo</quote> end up with a nicely formatted man page highlighting
918     the basic use of their application. Make sure that before you
919     release your program, you've planned for this.
920     </para>
921
922     <para>
923      Man pages are not difficult to write. There is excellent
924      documentation on the man page process available through the
925      <quote>The Linux Man-Page-HOWTO</quote> available through the
926      Linux Documentation project <acronym>(LDP)</acronym> written by
927      Jens Schweikhardt. It is available <ulink
928      url="http://www.schweikhardt.net/man_page_howto.html">from
929      Schweikhardt's site</ulink> or <ulink
930      url="http://www.linuxdoc.org/HOWTO/mini/Man-Page.html">from the
931      <acronym>LDP</acronym></ulink>.
932     </para>
933
934     <para>
935      It is also possible to write man pages using DocBook SGML and
936      convert them into man pages. Because man pages are so simple, I
937      have not been able to follow this up but would love help from
938      anyone who can give me more information on how exactly this is
939      done.
940     </para>
941    </sect3>
942
943    <sect3>
944     <title>Command line accessible documentation</title>
945
946     <para>
947      Most users will expect the most basic amount of documentation to
948      be easily available from the command line. For few programs should
949      then documentation extend for more than one screen (24 or 25
950      lines) but it should cover the basic usage, a brief (one or two
951      sentence) description of the program, a list of commands, all the
952      major options, and a pointer to more in-depth documentation for
953      those who need it. The command line documentation for Debian's
954      apt-get serves as an excellent example and a useful model:
955     </para>
956
957     <screen>
958 apt 0.3.19 for i386 compiled on May 12 2000  21:17:27
959 Usage: apt-get [options] command
960        apt-get [options] install pkg1 [pkg2 ...]
961
962 apt-get is a simple command line interface for downloading and
963 installing packages. The most frequently used commands are update
964 and install.
965
966 Commands:
967    update - Retrieve new lists of packages
968    upgrade - Perform an upgrade
969    install - Install new packages (pkg is libc6 not libc6.deb)
970    remove - Remove packages
971    source - Download source archives
972    dist-upgrade - Distribution upgrade, see apt-get(8)
973    dselect-upgrade - Follow dselect selections
974    clean - Erase downloaded archive files
975    autoclean - Erase old downloaded archive files
976    check - Verify that there are no broken dependencies
977
978 Options:
979   -h  This help text.
980   -q  Loggable output - no progress indicator
981   -qq No output except for errors
982   -d  Download only - do NOT install or unpack archives
983   -s  No-act. Perform ordering simulation
984   -y  Assume Yes to all queries and do not prompt
985   -f  Attempt to continue if the integrity check fails
986   -m  Attempt to continue if archives are unlocatable
987   -u  Show a list of upgraded packages as well
988   -b  Build the source package after fetching it
989   -c=? Read this configuration file
990   -o=? Set an arbitary configuration option, eg -o dir::cache=/tmp
991 See the apt-get(8), sources.list(5) and apt.conf(5) manual
992 pages for more information and options.
993     </screen>
994
995     <para>
996      It has become a GNU convention to make this information
997      accessible with the <quote>-h</quote> and the
998      <quote>--help</quote> options. Most GNU/Linux users will expect
999      to be able to retrieve basic documentation these ways so if you
1000      choose to use different method, be prepared for the flames and
1001      for the fallout that may result.
1002     </para>
1003    </sect3>
1004    <sect3>
1005     <title>Files users will expect</title>
1006     <para>
1007      In addition to man pages and online help, there are certain files
1008      where people will look to documentation, especially in any
1009      package containing source code. In a source distribution, most of
1010      these files can be stored in a the root directory of the source
1011      distribution or in a subdirectory of the root called
1012      <quote>doc</quote> or <quote>Documentation</quote>. These files include:
1013     </para>
1014     <para>
1015      <variablelist>
1016       <varlistentry>
1017        <term>README or Readme</term>
1018
1019        <listitem>
1020         <para>A document containing all the basic installation,
1021         compilation, and even basic use instructions that make up the
1022         bare minimum information needed to get the program up and
1023         running. A README is not your chance to be verbose but needs
1024         to be concise and effective. An ideal README is at least 30
1025         lines long and more no more than 250.</para>
1026        </listitem>
1027
1028       </varlistentry>
1029       <varlistentry>
1030        <term>INSTALL or Install</term>
1031
1032        <listitem>
1033         <para>The INSTALL file should be much shorter than the INSTALL
1034         file and should quickly and concisely describe how to build
1035         and install the program. Usually an install simply instructs
1036         the user to run ./configure; make; make install and touches on
1037         any unusual options that may be necessary. More advanced users
1038         can usually avoid them but it's good practice to at least
1039         glance at the file to understand what can be expected. For
1040         most relatively standard install procedures and for most
1041         programs, INSTALL files are as short as possible are rarely
1042         over 100 lines.</para>
1043        </listitem>
1044
1045       </varlistentry>
1046       <varlistentry>
1047        <term>Changelog, ChangeLog, CHANGELOG, or changelog</term>
1048
1049        <listitem>
1050         <para>A changelog is a simple file that every well-managed
1051         free software project should include. A changelog is simple
1052         the file that, as its name would imply, logs or documents the
1053         changes to a program. The most simple way to do a changelog is
1054         to simply keep a file with the source code for your program
1055         and add a section to the top of the changelog with each
1056         release describing what has been, changed, fixed, or added to
1057         the program. It's a good idea to post the changelog onto the
1058         website as well because it can help people decide whether they
1059         want or need to upgrade to a newer version or wait for a more
1060         significant upgrade.</para>
1061        </listitem>
1062
1063       </varlistentry>
1064       <varlistentry>
1065        <term><acronym>FAQ</acronym></term>
1066
1067        <listitem>
1068         <para>For those of you that don't already
1069         know. <acronym>FAQ</acronym> stands for Frequently Asked
1070         Questions and the file is a collection of exactly that. FAQs
1071         are not difficult to make. Simply make a policy that if you
1072         are asked a question or see a question on a mailing list two
1073         or more times, add it the question (and its answer) to your
1074         FAQs. FAQs are more optional than the files listed above but
1075         they can save your time, increase usability, and decrease
1076         headaches on all sides.</para>
1077        </listitem>
1078
1079       </varlistentry>
1080      </variablelist>
1081     </para>
1082    </sect3>
1083
1084    <sect3>
1085     <title>Website</title> 
1086     <para>
1087      It's only a sort of an issue of documentation but a good website
1088      is quickly becoming an essential part of any free software
1089      project. Your website should provide access to documentation (in
1090      <acronym>HTML</acronym> if possible). It should also include a
1091      section for news and events around your program and a section
1092      that details the process of getting involved with development or
1093      testing and creates an open invitation. It should also supply
1094      links to any mailing lists, similar websites, and directly to all
1095      the available ways of downloading your software.
1096     </para>
1097    </sect3>
1098
1099    <sect3>
1100     <title>Other documentation hints</title>
1101
1102     <para>
1103      It doesn't hurt to distribute any documentation for your program
1104      from your website or anywhere else (FAQs etc) with the
1105      program. Make a FAQ by cutting and posting common questions and
1106      answers from a mailing list or your own email. Then, don't
1107      hesitate through this in the programs tarball. If people don't
1108      need it, they will delete it. I can repeat it over and over:
1109      <emphasis>Too much documentation is not a sin.</emphasis>
1110     </para>
1111
1112     <para>
1113      All your documentation should be in plaintext, or, in cases where
1114      it is on your website primarily, in HTML. Everyone can cat a
1115      file, everyone has a pager, (almost) everyone can render
1116      HTML. <emphasis>You are welcome to distribute information in PDF,
1117      PostScript, RTF, or any number of other widely used formats but
1118      this information must also be available in plaintext or HTML or
1119      people will be very angry at you.</emphasis>
1120     </para>
1121    </sect3>
1122   </sect2>
1123
1124 <!-- Section2: presentation -->
1125
1126   <sect2 id="presentation">
1127    <title>Other Presentation Issues</title>
1128    <para>
1129     Many of the remaining issues surrounding the creation of a new
1130     free software program fall under what most people describe as
1131     common sense actions. Still, they are worth noting briefly in
1132     hopes that they may remind a developer of something they may have
1133     forgotten.
1134    </para>
1135
1136    <sect3>
1137     <title>Package formats</title>
1138     <para>
1139      Package formats may differ depending on the system you are
1140      developing for. For windows based software, Zip archives (.zip)
1141      usually serve as the package format of choice. If you are
1142      developing for GNU/Linux, *BSD, or any UN*X, make sure that your
1143      source code is always available in tar'ed and gzip'ed format
1144      (.tar.gz). UNIX compress (.Z) has gone out of style and
1145      usefulness and faster computers have brought bzip2 (.bz2) into
1146      the spot-lit as a more effective compression medium. I now make
1147      all my releases available in both gzip'ed and bzip2'ed formats.
1148     </para>
1149
1150     <para>
1151      Binary packages are largely distribution specific. You can build
1152      binary packages against a current version of a major
1153      distribution, you will only make your users happy. Try to foster
1154      relationships with users or developers of large distribution to
1155      develop a system for consistent binary packages. It's often a
1156      good idea to provide RedHat <acronym>RPM</acronym>'s (.rpm),
1157      Debian deb's (.deb) and source <acronym>RPM</acronym>'s
1158      <acronym>SRPM</acronym>'s. Binary packages can also be compiled
1159      against a specified system with specified libraries and
1160      distributed in tar.gz format as well. <emphasis>Remember: While
1161      these binaries packages are nice, getting the source packaged and
1162      released should always be your priority. Other can and will do
1163      the the binary packages for you.</emphasis>
1164     </para>
1165    </sect3>
1166
1167    <sect3>
1168     <title>Useful tidbits and presentation hints</title>
1169
1170     <para>
1171      <itemizedlist>
1172
1173       <listitem>
1174        <para>
1175         <emphasis>Make sure that your program can always be found in a
1176         single location.</emphasis> Often this means that you have a
1177         single directory accessible via <acronym>FTP</acronym> or
1178         <acronym>HTTP</acronym> where the newest version will be
1179         quickly recognized. One effective technique is a provide a
1180         symlink called <quote>projectname-latest</quote> that is
1181         always pointing to the most recent released or development
1182         version of your free software project.
1183        </para>
1184       </listitem>
1185
1186       <listitem>
1187        <para>
1188         <emphasis>Make sure that there is a consistent email address
1189         for bug reports.</emphasis> It's usually a good idea to make
1190         this something that is NOT your primary email address like
1191         projectname@host or projectname-bugs@host. This way if you
1192         ever decide to hand over maintainership or if your email
1193         address changes, you simply need to change where this email
1194         address forwards to. It also will allow for more than one
1195         person to deal with the influx of mail that is created if your
1196         project becomes as huge as you hope it will.
1197        </para>
1198       </listitem>
1199
1200      </itemizedlist>
1201     </para>
1202
1203    </sect3>
1204   </sect2>
1205  </sect1>
1206
1207 <!-- Section1: starting: END -->
1208
1209 <!-- Section1: developers -->
1210
1211  <sect1 id="developers">
1212   <title>Maintaining a Project: Interacting with Developers</title>
1213   <indexterm>
1214    <primary>fswd!developers</primary>
1215   </indexterm>
1216
1217   <para>
1218    Once you have gotten the project started, you have gotten over the
1219    most difficult hurdles in the development process of your
1220    program. Laying a firm foundation is essential, but the development
1221    process itself is equally important and provides an equal number of
1222    opportunities for failure. In the next two sections, I will and
1223    cover running a project by discussing how to maintain a project
1224    rough interactions with developers and with users.
1225   </para>
1226
1227   <para>
1228    In releasing your program, your program becomes free software. This
1229    transition is more than just a larger user base. By releasing your
1230    program as free software, <emphasis>your</emphasis> software
1231    becomes the <emphasis>free software community's</emphasis>
1232    software. The direction of your software's development will be
1233    reshaped, redirected, and fully determined by your users and, to a
1234    larger extent, by other developers in the community.
1235   </para>
1236
1237   <para>
1238    The major difference between free software development and propriety
1239    software development is the developer base. As the leader of a free
1240    software project, you need to attract and keep developers in a way
1241    that leaders of proprietary software projects simply don't have to
1242    worry about. <emphasis>As the person leading development of a free
1243    software project, you must harness the work of fellow developers by
1244    making responsible decisions and by and by choosing not to make
1245    decisions responsibly. You have to direct developers without being
1246    overbearing or bossy. You need to strive to earn respect and never
1247    forget to give it.</emphasis>
1248   </para>
1249
1250 <!-- Section2: delegation  -->
1251
1252   <sect2 id="delegation">
1253    <title>Delegating Work</title>
1254
1255    <para>
1256     By now, you've hypothetically followed me through the early
1257     writing of a piece of software, the creation of a website and
1258     system of documentation and and we've gone ahead and (as will be
1259     discussed in <xref linkend="releasing">) released it to the rest
1260     of the world. Times passes, and if things go well, people become
1261     interested and want to help. The patches begin flowing in.
1262    </para>
1263
1264    <para>
1265     <emphasis>Like the parent of any child who grows up, it's now time
1266     to wince and smile and do most difficult thing in any parents
1267     life: It's time to let go.</emphasis>
1268    </para>
1269
1270    <para>
1271     Delegation is the political way of describing this process of
1272     <quote>letting go.</quote> It is the process of handing some of
1273     the responsibility and power over your project to other responsible
1274     and involved developers. It is difficult for anyone who has
1275     invested a large deal of time and energy into a project but it
1276     essential for the growth of any free software project. One person
1277     can only do so much. <emphasis>A free software project is nothing
1278     without the involvement of a group of developers. A group of
1279     developers can only be maintained through respectful and
1280     responsible leadership and delegation.</emphasis>
1281    </para>
1282
1283    <para>
1284     As your project progresses, you will notice people who are putting
1285     significant amounts of time and effort into your project. These
1286     will be the people submitting the most patches, posting most on
1287     the mailing lists, engaging in long email discussions. It is your
1288     responsibility to contact these people and to try and shift some of
1289     the power and responsibility of your position as the project's
1290     maintainer onto them (if they want it). There are several easy
1291     ways you can do this:
1292    </para>
1293
1294    <sect3>
1295     <title>How to delegate</title>
1296  
1297     <para>
1298      Like anything, its easier to see how others delegate than to do
1299      it yourself. You may find that other developers seem even more
1300      experienced or knowledgeable than you. Your job as a maintainer
1301      does not mean you have to have to be the best or the
1302      brightest. It means you need are responsible for showing good
1303      judgment and for recognizing solutions that are maintainable and
1304      are not. In a sentence: <emphasis>Keep an eye out for other
1305      qualified developers who show an interest and sustained
1306      involvement with your project and try and shift responsibility
1307      towards them.</emphasis> The following ideas might be good places
1308      to start or good sources of inspiration:
1309     </para>
1310  
1311     <sect4>
1312      <title>Allow a larger group of people write access to your CVS
1313      repository and make real efforts towards rule by a
1314      committee</title>
1315
1316      <para>
1317       <ulink url="http://httpd.apache.org/">Apache</ulink> is an
1318       example of a project that is run by small group of developers
1319       who vote on major technical issues and the admission of new
1320       members and all have write access to the main source
1321       repository. Their process is detailed <ulink
1322       url="http://httpd.apache.org/ABOUT_APACHE.html">online.</ulink>
1323      </para>
1324
1325      <para>
1326       The <ulink url="http://www.debian.org/"> Debian Project</ulink>
1327       is an extreme example of rule by committee. At current count,
1328       more than 700 developers have full responsibility for certain
1329       aspects of the projects. All these developers can upload into
1330       the main FTP servers, and vote on major issues. Direction for
1331       the project is determined by the project <ulink
1332       url="http://www.debian.org/social_contract">social
1333       contract</ulink> and a <ulink
1334       url="http://www.debian.org/devel/constitution">constitution</ulink>. To
1335       facilitate this system, there are special teams (i.e. the
1336       install team, the Japanese language team) and a technical
1337       committee and a project lead. There is a project leader as well
1338       but the leader's main responsibility is to, <quote>Appoint
1339       Delegates or delegate decisions to the Technical
1340       Committee.</quote>
1341      </para>
1342
1343      <para>
1344       While both of these projects operate on a scale that your
1345       project will not (at least initially), their example is
1346       helpful. Debian's idea of a project who lead who can do
1347       <emphasis>nothing</emphasis> but delegate can serve as a
1348       caricature of how a project can involve and empower a huge
1349       number of developers and grow to a huge size.
1350      </para>
1351
1352     </sect4>
1353
1354     <sect4 id="releasemanager">
1355      <title>Publicly appoint someone as the release manager for a
1356        specific release.</title>
1357
1358      <para>
1359       A release manager is usually responsible for coordinating
1360       testing, enforcing a code freeze, being responsible for
1361       stability and quality control, packaging up the software, and
1362       placing it in the appropriate places to be downloaded.
1363      </para>
1364
1365      <para>
1366       This use of the release manager is a good way to give yourself a
1367       break and to shift the responsibility for accepting and
1368       rejecting patches to someone else. It is a good way of very
1369       clearly defining a chunk of work on the project as belonging to
1370       a certain person and its a great way of giving yourself a break.
1371      </para>
1372     </sect4>
1373
1374     <sect4 id="delegatebranch">
1375      <title>Delegate control of an entire branch.</title>
1376      <para>
1377       If your project chooses to have branches (as described in <xref
1378       linkend="branches">), it might be a good idea to appoint someone
1379       else to be the the head of a branch. If you like focusing your
1380       energy on development releases and the implementation of new
1381       features, had total control over the stable releases to a
1382       well-suited developer.
1383      </para>
1384
1385      <para>
1386       The author of Linux, Linus Torvalds, came out and crowned Alan
1387       Cox as <quote>the man for stable kernels.</quote> All patches
1388       for stable kernels go to Alan and, if Linus were to be taken
1389       away from work on Linux for any reason, Alan Cox would be more
1390       than suited to fill his role as the acknowledged heir to the
1391       Linux maintainership.
1392      </para>
1393     </sect4>
1394    </sect3> 
1395   </sect2>
1396
1397 <!-- Section2: patching -->
1398
1399   <sect2 id="patching">
1400    <title>Accepting and Rejecting Patches</title>
1401    <para>
1402     This HOWTO has already touched on the fact that as the maintainer
1403     of a free software project, one of primary and most important
1404     responsibilities will be accepting and rejecting patches submitted
1405     to you by other developers.
1406    </para>
1407
1408    <sect3>
1409     <title>Technical judgment</title>
1410
1411     <para>
1412      In <emphasis>Open Source Development with CVS</emphasis>, Karl
1413      Fogel makes a convincing argument that the most important things
1414      to keep in mind are a firm knowledge of the scope of your program
1415      (that's the <quote>idea</quote> I talked about in <xref
1416      linkend="chooseproject">) and the ability to recognize,
1417      facilitate, and direct <quote>evolution</quote> of a free
1418      software program so that the program can grow and change and
1419      incorporate functionality that was originally unforeseen but avoid
1420      digressions that might expand the scope of the program too much
1421      and result and push the project towards an early death under its
1422      own weight and unwieldiness. These are the criteria that you as a
1423      project maintainer should take into account each time you receive
1424      a patch.
1425     </para>
1426
1427     <para>
1428      Fogel elaborates on this again and states the <quote>the
1429      questions to ask yourself when considering whether to implement
1430      (or approve) a change are:</quote>
1431     </para>
1432
1433     <para>
1434      <itemizedlist>
1435
1436       <listitem>
1437        <para>Will it benefit a significant percentage of the program's
1438        user community?</para>
1439       </listitem>
1440
1441       <listitem>
1442        <para>Does it fit within the program's domain or within a
1443        natural, intuitive extension of that domain?</para>
1444       </listitem>
1445
1446      </itemizedlist>
1447     </para>
1448
1449     <para>
1450      The answers to these questions are never straightforward and its
1451      very possible (and even likely) that the person who submitted the
1452      patch may feel differently about the answer to those questions
1453      than you do. However, if you feel that that the answer to either
1454      of those questions is <quote>no,</quote> it is your responsibility
1455      to reject the change. If you fail to do this, the project will
1456      become unwieldy and unmaintainable and will ultimately fail.
1457     </para>
1458    </sect3>
1459
1460    <sect3>
1461     <title>Rejecting patches</title>
1462
1463     <para>
1464      Rejecting patches is probably the most difficult and the most
1465      sensitive job that the maintainer of any free software project
1466      has to face. But sometimes it has to be done. I mentioned earlier
1467      (in <xref linkend="developers"> and in <xref
1468      linkend="delegation">) that any developer needs to try and
1469      balance your responsibility and power to make what you think are
1470      the best technical decisions with the fact that you will lose
1471      support from other developers if you seem like you are on a
1472      power trip or being overly bossy or possessive of a community-based
1473      project. I recommend that you keep three major facts in mind when
1474      rejecting patches (or other changes):
1475     </para>
1476
1477     <sect4>
1478      <title>Bring it to the community</title>
1479      <para>
1480       One of the best ways of justifying  a decision to reject a patch
1481       and working  to  not seem like  you  keep an  iron grip  on your
1482       project is by  not making the  decision  alone at all. It  might
1483       make  sense  to  turn over  larger  proposed  changes  or more
1484       difficult decisions to a development mailing list where they can
1485       be discussed. There will be some patches (bug fixes, etc.) which
1486       will  definitely be accepted  and some that you  feel are so off
1487       base that they do not even merit further discussion. It is those
1488       that fall into the grey area between these two groups that might
1489       merit a quick forward to a mailing list.
1490      </para>
1491
1492      <para>
1493       I recommend this process wholeheartedly. As the project
1494       maintainer you are worried about making the best decision for
1495       the project, for the project's users and developers, and for
1496       yourself as a responsible project leader. Turning things over to
1497       an email list will demonstrate your own responsible and
1498       responsive leadership as it tests and serves the interests of
1499       your software's community.
1500      </para>
1501     </sect4>
1502
1503     <sect4>
1504      <title>Technical issues is not always good justification</title>
1505      <para>
1506       Especially towards the beginning, you will find that many
1507       changes are difficult to implement, introduce new bugs, or have
1508       other technical problems. Try to see past these. Especially with
1509       added functionality, good ideas do not always come from good
1510       coders. Technical merit is a valid reason to postpone the
1511       application of a patch but it is not always a good reason to
1512       reject a change outright. Even small changes are worth the
1513       effort of working with the developer submitting the patch to iron out bugs and
1514       incorporate the change if you thing you think it seems like a
1515       good addition to your project. The effort on your part will work
1516       to make your project a community project and it will pull a new
1517       or less experienced developer onto your project and even teach
1518       them something that might help them in their next patch.
1519      </para>
1520     </sect4>
1521
1522     <sect4>
1523      <title>Common courtesy</title>
1524      <para>
1525       It should go without saying but, <emphasis>above all and in all
1526       cases, just be nice.</emphasis> If someone has an idea and cares
1527       about it enough to write some code and submit a patch, they
1528       care, they are motivated, and they are already involved. Your
1529       goal as the maintainer is make sure they submit again. They may
1530       have thrown you a dud this time but next time may be the idea or
1531       feature that revolutionizes your project. 
1532      </para>
1533
1534      <para>
1535       It is your responsibility to first justify your action to not
1536       incorporate their change clearly and concisely. Then thank
1537       them. Let them know that you a appreciate their help and feel
1538       horrible that you can't incorporate their change. Let them know
1539       that you look forward to their staying involved and you hope
1540       that the next patch or idea meshes better with your project
1541       because you appreciate their work and want to see it in the
1542       project. If you have ever had a patch rejected that put a large
1543       deal of time, thought, and energy into, you remember how it
1544       feels and it feels bad. Keep this in mind when you have to let
1545       someone down. It's never easy but you need to do everything you
1546       have to make it as not-unpleasant as possible.
1547      </para>
1548     </sect4>
1549    </sect3>
1550   </sect2>
1551
1552 <!-- Section2: branches  -->
1553
1554   <sect2 id="branches">
1555    <title>Stable and Development Branches</title>
1556
1557    <para>
1558     The idea of stable and development branches has already been
1559     described briefly in <xref linkend="chooseversioning"> and in
1560     <xref linkend="delegatebranch">. These alludes attest to the fact
1561     to some of the ways that multiple branches can affect your
1562     software. Branches can let you avoid (to some extent) some of the
1563     problems around rejecting patches (as described in <xref
1564     linkend="patching">) by allowing you to temporarily compromise the
1565     stability of your project without affected those users who need
1566     that stability.
1567    </para>
1568
1569    <para>
1570     The most common way of branching your project is to have one
1571     branch that is stable and one that is development. This is the
1572     model followed by the Linux kernel that is described in <xref
1573     linkend="chooseversioning">. In this model, there is always one
1574     branch that is stable and always one that is in
1575     development. Before any new release, the development branch goes
1576     into a <quote>feature freeze</quote> where major changes and added
1577     features are rejected or put on hold under the development kernel
1578     is released as the new stable branch and major development begins
1579     again on the development branch. Bug fixes and small changes that
1580     are unlikely to have any large negative repercussions are
1581     incorporated into the stable branch also to the development
1582     branch.
1583    </para>
1584
1585    <para>
1586     Linux's model is an extreme one. On many projects, there is no
1587     need to have two versions always available. It may make sense to
1588     have two versions only near a release. The Debian project has
1589     historically made both a stable and an unstable distribution
1590     available but has expanded to this to include: stable, unstable,
1591     testing, experimental, and (around release time) a frozen
1592     distribution that only incorporates bug fixes during the
1593     transition from unstable to stable. There are few projects whose
1594     size would necessitate a system like Debian but their use of
1595     branches helps demonstrate how they can be used to balance
1596     consistent and effective development with the need to make regular
1597     and usable releases.
1598    </para>
1599
1600    <para>
1601     In trying to set up a development tree for yourself, there are
1602     several things that might be useful to keep in mind:
1603    </para>
1604
1605    <para>
1606     <variablelist>
1607
1608      <varlistentry>
1609       <term>Minimize the number of branches</term>
1610       <listitem>
1611        <para>Debian may be able to make good use of four or five
1612        branches but it contains gigabytes of software in over 5000
1613        packages compiled for a 5-6 different architectures. Two is a
1614        good number. Too many branches will confuse your users (I can't
1615        count how many times I had to describe Debian's system when it
1616        only had 2 and sometimes 3 branches!), potential developers and
1617        even yourself. Branches can help but they come at a cost so use
1618        them very sparingly.</para>
1619       </listitem>
1620      </varlistentry>
1621
1622      <varlistentry>
1623       <term>Make sure that all your different branches are explained</term>
1624       <listitem>
1625        <para>As I mentioned in the preceding paragraph, different
1626        branches <emphasis>will</emphasis> confuse your users. Do
1627        everything you can to avoid this by clearly explaining the
1628        different branches in a prominent page on your website and in a
1629        Readme file in the <acronym>FTP</acronym> or
1630        <acronym>HTTP</acronym> directory.</para>
1631
1632        <para>
1633         I might also recommend against a mistake that I think Debian
1634         has made. The terms <quote>unstable,</quote>
1635         <quote>testing,</quote> and <quote>experimental</quote> are
1636         vague and difficult to rank in order of stability (or
1637         instability as the case may be). Try explaining to someone
1638         that <quote>stable</quote> actually means <quote>ultra
1639         stable</quote> and that <quote>unstable</quote> doesn't
1640         actually include any unstable software but is really stable
1641         software that is untested as a distribution.
1642        </para>
1643
1644        <para>
1645         If you are going to do branches, especially early on, keep in
1646         mind that people are conditioned to understand the terms
1647         <quote>stable</quote> and <quote>development</quote> and you
1648         probably can't go wrong with this simple and common division of
1649         branches.
1650        </para>
1651       </listitem>
1652      </varlistentry>
1653
1654      <varlistentry>
1655       <term>Make sure all your branches are always available</term>
1656       <listitem>
1657        <para>Like a lot of document, this should probably should go
1658        without saying but experience has taught me that it's not
1659        always obvious to people. It's a good idea to physically split
1660        up different branches in different directories or directory
1661        trees on your <acronym>FTP</acronym> or <acronym>HTTP</acronym>
1662        site. Linux accomplishes this by having all the v2.2 and a v2.3
1663        subdirectory where it is immediately obvious (after you know
1664        their version numbering scheme) which directory is the most
1665        recent stable and the current development releases. Debian
1666        accomplishes this by naming all their distribution by name and
1667        then changing symlinks named <quote>stable,</quote>
1668        <quote>unstable</quote> and <quote>frozen</quote> to point to
1669        which ever distribution (by name) is in whatever stage. Both
1670        methods work and their are others. In any case, it is important
1671        that different branches are always available, are accessible
1672        from consistent locations, and that different branches are
1673        clearly distinguished from each other so your users know
1674        exactly what they want to be downloading and where to get
1675        it.</para>
1676       </listitem>
1677      </varlistentry>
1678
1679     </variablelist>
1680    </para>
1681
1682   </sect2>
1683
1684 <!-- Section2: otherdev -->
1685
1686   <sect2 id="otherdev">
1687    <title>Other Development issues</title>
1688    <para>
1689     There are more issues around surrounding interaction with
1690     developers in a free software project that I can touch on in great
1691     detail in a HOWTO of this size. Please don't hesitate to contact
1692     me if you see any major omissions. Other smaller issues that are
1693     worth mentioning are:
1694    </para>
1695
1696    <sect3>
1697     <title>Freezing</title>
1698     <para>
1699      For those projects that choose to adopt a split development model
1700      (<xref linkend="branches">), freezing is a concept that is worth
1701      becoming familiar with. 
1702     </para>
1703
1704     <para>
1705      Freeze come in two major forms. A <quote>feature freeze</quote>
1706      is a period when no significant functionality is added to a
1707      program. It is a period where established functionality (even
1708      skeletons of barely working functionality) can be improved and
1709      perfected. It is a period where bugs are fixed. This type of
1710      freeze is usually applied some period (a month or two) before a
1711      release. It is easy to push a release back as you wait for
1712      <quote>one more feature</quote> and a freeze helps to avoid this
1713      situation by drawing the much needed line in the sand. It gives
1714      developers room they need to get a program ready for release.
1715     </para>
1716
1717     <para>
1718      The second type of freeze is a <quote>code freeze</quote> which
1719      is much more like a released piece of software. Once a piece of
1720      software has entered a code freeze, all changes to the code are
1721      frowned upon and only changes that fix known bugs are
1722      permitted. This type of freeze usually follows a <quote>feature
1723      freeze</quote> and directly precedes a release. Most released
1724      software is in what could be interpreted as a sort of high
1725      level<quote>code freeze.</quote>
1726     </para>
1727
1728     <para>
1729      Even you do not choose to appoint a release manager (<xref
1730      linkend="releasemanager">), you will have an easier time
1731      justifying the rejection or postponement of patches (<xref
1732      linkend="patching"> before a release with a publicly stated
1733      freeze in effect.
1734     </para>
1735    </sect3>
1736
1737    <sect3>
1738     <title>Forking</title>
1739     <para>
1740      Forks are the most extreme interpretation of a branch. A fork is
1741      when a group of developers takes code from a free software
1742      project and actually starts a brand new free software
1743      project. The most famous example of a fork is Emacs and
1744      XEmacs. Both emacsen are based on an almost identical code-base
1745      but for technical, political, and philosophical reasons,
1746      development was split into two projects which now compete with
1747      each other.
1748     </para>
1749
1750     <para>
1751      The short version of the fork section is, <emphasis>don't do
1752      them.</emphasis> Forks force developers to choose one project to
1753      work with, cause nasty political divisions, redundancy of work.
1754      Luckily, usually the threat of the fork is enough to scare the
1755      maintainer or maintainers of a project into changing the way they
1756      run their project to avoid it.
1757     </para>
1758
1759     <para>
1760      In his chapter on <quote>The Open Source Process,</quote> Karl
1761      Fogel describes how to do a fork if you absolutely must. If you
1762      have determined that is absolutely necessary and that the
1763      differences between you and the people threatening to fork are
1764      absolutely unresolvable, I recommend Fogel's book as a good place
1765      to start.
1766     </para>
1767    </sect3>
1768   </sect2>
1769  </sect1>
1770
1771 <!-- Section1: users -->
1772
1773  <sect1 id="users">
1774   <title>Maintaining a Project: Interacting with Users</title>
1775   <indexterm>
1776    <primary>fswd!users</primary>
1777   </indexterm>
1778
1779   <para>
1780    If you've worked your way up to here, congratulations, you are
1781    nearing the end of this document. This final section describes some
1782    of the situations in which you, in your capacity as project
1783    maintainer, will be interacting with users and gives some
1784    suggestions on how these situations might be handled effectively.
1785   </para>
1786
1787   <para>
1788    Interacting with users is difficult. In our discussion of
1789    interaction with developers, the underlying assumption is that in a
1790    free software project, a project maintainer must constantly strive to
1791    attract and keep developers who can easily leave at any time.
1792   </para>
1793
1794   <para>
1795    Users in the free software community are different than users in
1796    the world of proprietary software and they should be treated
1797    differently. Some ways in which the groups differ significantly
1798    follow:
1799   </para>
1800
1801   <para>
1802    <itemizedlist>
1803
1804     <listitem>
1805      <para>The lines between users and developers are blurred in ways
1806      that is totally foreign to any proprietary development
1807      model. Your users are often your developers and vice
1808      versa.</para>
1809     </listitem>
1810
1811     <listitem>
1812      <para>In the free software world, you are often your users only
1813      choice. Because there is such an emphasis on not replicating the
1814      work of others in the free software community and because the
1815      element of competition present in the propriety software model is
1816      absent (or at least in an extremely different form) in the free
1817      software development model your users will probably be the only
1818      project that does what you do (or at least the only one that does
1819      what you do in the way that you do it). This means your
1820      responsiveness to your users is even more important in that in
1821      the proprietary world.</para>
1822     </listitem>
1823
1824     <listitem>
1825      <para>In an almost paradoxical situation, free software projects
1826      have less immediate or dire consequences for ignoring their
1827      users--it is often easier to do. Because you don't usually need
1828      to compete with another product in the free software model,
1829      chances are good that you will not be scrambling to gain the
1830      features of the competitor's newest program. This means that your
1831      development process will have to be directed either internally,
1832      by your users or both.</para>
1833     </listitem>
1834    </itemizedlist>
1835   </para>
1836
1837   <para>
1838    Trying to tackle this unique situation can only be done
1839    indirectly. Developers and maintainers need to listen to users and
1840    to try and be as responsive as possible. A solid knowledge of the
1841    situation recounted above is any free software developers best tool
1842    for shifting his development or leadership style to fit the unique
1843    process of free software development. This chapters will try and
1844    introduce some of the more difficult or important points in any
1845    projects interactions with users and give some hints on how to
1846    tackle these.
1847   </para>
1848
1849 <!-- Section2: testing -->
1850
1851   <sect2 id="testing">
1852    <title>Testing and Testers</title>
1853
1854    <para>
1855     In addition to your users being your developers, they are also
1856     (and perhaps more commonly) your testers. Before I get flamed, I
1857     should rephrase my sentence: <emphasis>some</emphasis> users are
1858     your testers.
1859    </para>
1860
1861    <para>
1862     It is important that this distinction be made early on because not
1863     all of your users wants to be testers. Many users want to use
1864     stable software and don't care if they don't have the newest
1865     greatest software with the latest and greatest features. These
1866     users except a stable, tested piece of software with major or
1867     obvious bugs worked out or openly declared and will be angry if
1868     they find themselves in a testing position. This is yet another
1869     way in which a split development model (as mentioned in <xref
1870     linkend="branches">) might come in handy.
1871    </para>
1872
1873    <sect3>
1874     <title>Automated testing</title>
1875     <para>
1876      For many programs, many common and mistakes can be caught by
1877      automated means. Automated tests tend to be pretty good at
1878      catching errors that you've run into several times before or
1879      something you just forget and not very good at finding errors,
1880      even major ones, that were totally unforeseen.
1881     </para>
1882
1883     <para>
1884      CVS comes with a bourne shell script called sanity.sh that is
1885      worth looking at. Debian uses a program called lintian that
1886      checks Debian packages for all of the most common errors. While
1887      using these scripts may not be possible, there is a host of other
1888      sanity checking software on the net that may be applicable (feel
1889      free to email any recommendations). None of these will create a
1890      bug-free release but they will avoid at least some major
1891      oversights. Finally, if your programs become a long term
1892      endeavor, you will find that there are certain errors that you
1893      tend to make over and over. Start a collection of scripts that
1894      check for these errors to help prevent them in the future.
1895     </para>
1896    </sect3>
1897
1898    <sect3>
1899     <title>Testing by testers</title>
1900     <para>
1901      For any program that depends on user interactivity, many bugs
1902      will only be uncovered through testing by users actually clicking
1903      the keys and pressing the mouse buttons. For this you need
1904      testers and as many testers as possible.
1905     </para>
1906
1907     <para>
1908      The most difficult part of testing is finding testers. It's
1909      usually a good tactic to post a message to a relevant mailing
1910      list or news group announcing a specific proposed release date
1911      and outline the functionality of the program. If you put some
1912      time into the announcement, you are sure to get a few bites.
1913     </para>
1914
1915     <para>
1916      The second most difficult part of testing is keeping your testers
1917      and keeping them actively involved in the testing
1918      process. Fortunately, there are some tried and true tactics that
1919      can applied towards this end:
1920     </para>
1921
1922     <para>
1923      <itemizedlist>
1924
1925       <listitem>
1926        <para><emphasis>Make things simple for your testers.</emphasis>
1927        Your testers are doing you a favor so make it as easy as
1928        possible. This means that you should be careful to package your
1929        software in a way that is easy to find, unpack, install, and
1930        uninstall. This also means you should explain what you are
1931        looking for to each tester and make the means for reporting
1932        bugs simple and well established. The key is to provide as much
1933        structure as possible to make your tester's job easy and
1934        maintain as much flexibility as possible for those that want to
1935        do things a little differently.</para>
1936       </listitem>
1937
1938       <listitem>
1939        <para><emphasis>Be responsive to your testers.</emphasis> When
1940        your testers submit bugs, respond to them and respond
1941        quickly. Even if you are only responding to tell them that the
1942        bug has already been fixed, quick and consistent response make
1943        them feel like their work is heard, important, and
1944        appreciated.</para>
1945       </listitem>
1946
1947       <listitem>
1948        <para><emphasis>Thank your testers.</emphasis> Thank them
1949        personally each time they send you patch. Thank them publicly
1950        in the documentation and the about section of your program. You
1951        appreciate your testers and your program would not be possible
1952        without their help. Make sure they know and pat them on the
1953        back by making sure the rest of the world knows it too. It will
1954        be appreciated more than you expected.</para>
1955       </listitem>
1956
1957      </itemizedlist>
1958     </para>
1959    </sect3>
1960   </sect2>
1961
1962 <!-- Section2: support  -->
1963
1964   <sect2 id="support">
1965    <title>Setting up a Support Infrastructure</title>
1966
1967    <para>
1968     While testing is important, the large part of your interactions
1969     and responsibility to your users falls under the category of
1970     support. The best way to make sure your users are adequately
1971     supported in using your program is to set up a good infrastructure
1972     for this purpose so that your developers and users help each other
1973     and less of the burden falls on you while people get quicker and
1974     better responses to their questions. This infrastructure comes in
1975     several forms:
1976    </para>
1977
1978    <sect3>
1979     <title>Documentation</title>
1980     <para>
1981      It should not come as any surprise that the key element to any
1982      support infrastructure is good documentation. This topic was
1983      large covered in <xref linkend="documentation"> and will not be
1984      repeated here.
1985     </para>
1986    </sect3>
1987
1988    <sect3>
1989     <title>Mailing lists</title>
1990     <para>
1991      Aside from documentation, effective mailing lists will be your
1992      greatest tool in supporting user support. Running a mailing list
1993      well is more complicated than installing mailing list software
1994      onto a machine. 
1995     </para>
1996
1997     <sect4>
1998      <title>Separate lists</title>
1999      
2000      <para>
2001       A good idea is too separate your user and development mailing
2002       lists (perhaps into project-user@host and project-devel@host)
2003       and enforce the division. If people post a development question
2004       onto -user, politely ask them to repost it onto -devel and vise
2005       versa. Subscribe yourself to both groups and encourage primarily
2006       developers to do the same.
2007      </para>
2008
2009      <para>
2010       This system provides so that no one person is stuck doing all of
2011       the support work and works so that users learn more about the
2012       program, they can help new users with their questions.
2013      </para>
2014     </sect4>
2015
2016     <sect4>
2017      <title>Choose mailing list software well</title>
2018      <para>
2019       Please don't make the selection of mailing list software
2020       lightly. Please consider easy accessibility by users without a
2021       lot of technical experience so you want to be as easy as
2022       possible. Web accessibility to an archive of the list is also
2023       important.
2024      </para>
2025
2026      <para>
2027       The two biggest free software mailing list programs are <ulink
2028       url="http://www.greatcircle.com/majordomo/">majordomo</ulink>
2029       and <ulink url="http://www.list.org/">GNU Mailman</ulink>. A
2030       long time advocate of majordomo, I would now recommend any
2031       project choose GNU Mailman. It fulfills the criteria listed above
2032       and makes it easier to do. It provides a good mailing list
2033       program for a free software project maintainer as opposed to a
2034       good mailing list application for a mailing list administrator.
2035      </para>
2036
2037      <para>
2038       There are other things you want to take in setting up your
2039       list. If it is possible to gate your mailing lists to USENET and
2040       provide them in digest form as well as making them accessible on
2041       the web, you will please some users and work to make the support
2042       infrastructure slightly more accessible.
2043      </para>
2044     </sect4>
2045    </sect3>
2046
2047    <sect3>
2048     <title>Other support ideas</title>
2049
2050     <para>
2051      A mailing list and accessible documentation all you can do to set
2052      up good user support infrastructure. Be creative. If you stumble
2053      across something works well, email me and I'll include it here in
2054      the HOWTO.
2055     </para>
2056     <sect4>
2057      <title>Make your self accessible</title>
2058      <para>
2059       You can not put to few methods to access you. If you hang out in
2060       an <acronym>IRC</acronym> channel, don't hesitate to list in
2061       your projects documentation. List email and snail mail
2062       addresses, or ways to reach you via <acronym>ICQ</acronym>,
2063       <acronym>AIM</acronym>, or Jabber.
2064     </para>
2065     </sect4>
2066
2067     <sect4>
2068      <title>Bug management software</title>
2069      <para>
2070       For many large software projects, use of bug management software
2071       is essential to keep track of which bugs have been fixed, which
2072       bugs have not been fixed, and which bugs are being fixed by
2073       which people. Debian uses the <ulink
2074       url="http://bugs.debian.org">Debian Bug Tracking System</ulink>
2075       (<acronym>BTS</acronym>) although it may not be best choice for
2076       every project (it seems to currently be buckling under its own
2077       weight. As well as a damn good web browser, the mozilla project
2078       has spawned a sub-project resulting in a bug tracking system
2079       called <ulink
2080       url="http://www.mozilla.org/projects/bugzilla/">bugzilla</ulink>.
2081      </para>
2082
2083      <para>
2084       These systems (and others like them) can be unwieldy so
2085       developers should be careful to not spend more time on the bug
2086       tracking system than on the bugs or the projects themselves. If
2087       a project continues to grow, use of a bug tracking system can
2088       provide an easy standard way for users and testers to report
2089       bugs and for developers and maintainers to fix them in an
2090       orderly fashion.
2091      </para>
2092     </sect4>
2093    </sect3>
2094   </sect2>
2095
2096 <!-- Section2: releasing -->
2097
2098   <sect2 id="releasing">
2099    <title>Releasing Your Program</title>
2100
2101    <para>
2102     As mentioned earlier in the HOWTO, the first rule or releasing is,
2103     <emphasis>release something useful.</emphasis> Non-working or
2104     not-useful software will not attract anyone to your
2105     project. People will be turned off of your project and be likely
2106     to simply gloss over it next time they see a new version
2107     announced. Half-working software, if useful, will intrigue people,
2108     whet their appetites for the version to come, and encourage them
2109     to join the development process.
2110    </para>
2111
2112    <sect3>
2113     <title>When to release</title>
2114
2115     <para>
2116      Making the decision to release your software for the first time
2117      is an incredibly important and incredibly stressful decision. But
2118      it needs to be done. My advice is to try and make something that
2119      is complete enough to be usable and incomplete enough to allow
2120      for flexibility and imagination by your future developers. It's
2121      not an easy decision. Ask for help on a local Linux User Group
2122      mailing list or from a group of developer friends.
2123     </para>
2124
2125     <para>
2126      One tactic is to first do an <quote>alpha</quote> or
2127      <quote>beta</quote> release as described below in <xref
2128      linkend="alphabeta">. However, most of the guidelines described
2129      above still apply.
2130     </para>
2131
2132     <para>
2133      <emphasis>When you feel in your gut it is time and you feel
2134      you've weighed the situation well several times, cross your
2135      fingers and take the plunge.</emphasis>
2136    </para>
2137    </sect3>
2138
2139    <sect3>
2140     <title>How to release</title>
2141
2142     <para>
2143      If you've followed the guidelines described in this HOWTO up
2144      until this point, the mechanics of doing a release are going to
2145      be the easy part of releasing. If you have set up a consistent
2146      distribution locations and the other infrastructure described in
2147      the preceding sections, releasing should be as simple as
2148      building the package, checking it once over, and uploading it
2149      into the appropriate place and then reflecting the release on
2150      your website.
2151     </para>
2152    </sect3>
2153
2154    <sect3 id="alphabeta">
2155     <title>Alpha, beta, and development releases</title>
2156
2157     <para>
2158      When contemplating releases, it worth considering the fact that
2159      not every release needs to be a full numbered release. Software
2160      users are accustomed to pre-releases but you must be careful to
2161      label these releases accurately or they cause more problems then
2162      they are worth.
2163     </para>
2164
2165     <para>
2166      <variablelist>
2167
2168       <varlistentry>
2169        <term>alpha releases</term>
2170        <listitem>
2171         <para>Alpha releases are expected to be unstable, perhaps a
2172         little unsafe, but definitely usable. Alpha versions should
2173         have full functionality and limited testing. They can have
2174         known bugs and kinks that have yet to be worked out. Before
2175         sure to keep in mind that <emphasis>alpha releases are still
2176         releases</emphasis> and people are not going to be expecting a
2177         nightly build from the CVS source. An alpha should work and
2178         have minimal testing and bug fixing already finished.</para>
2179        </listitem>
2180       </varlistentry>
2181
2182       <varlistentry>
2183        <term>beta releases</term>
2184        <listitem>
2185         <para>Beta releases are general expected to be usable and
2186         slightly unstable, although definitely
2187         <emphasis>not</emphasis> unsafe. Beta releases usually
2188         preclude a full release by under a month. They can contain
2189         small known bugs but no major ones. All major functionality
2190         should be fully implemented although the exact mechanics can
2191         still be worked out. Beta releases are great tool to whet the
2192         appetites of potential users by giving them a very realistic
2193         view of where your project is going in the very near future
2194         and can help keep interest by giving people
2195         <emphasis>something.</emphasis></para>
2196        </listitem>
2197       </varlistentry>
2198
2199       <varlistentry>
2200        <term>development releases</term>
2201        <listitem>
2202         <para>Development release is much more vague term than
2203         <quote>alpha</quote> or <quote>beta</quote>. I usually choose
2204         to reserve the term for discussion of a development
2205         branch. There are other ways to use the term. So many in fact,
2206         that I feel the term has been cheapened. The popular window
2207         manager <ulink
2208         url="http://www.enlightenment.org">Enlightenment</ulink> has
2209         released <emphasis>nothing but</emphasis> development
2210         releases. Most often, the term is used to describe releases
2211         that are not even to alpha or beta stages though and if I were
2212         to release a pre-alpha release in order to keep interest in my
2213         project live, this is probably how I would have to label
2214         it.</para>
2215        </listitem>
2216       </varlistentry>
2217
2218      </variablelist>
2219
2220     </para>
2221    </sect3>
2222   </sect2>
2223
2224 <!-- Section2: announcing  -->
2225
2226   <sect2 id="announcing">
2227    <title>Announcing Your Project</title>
2228
2229    <para>
2230     Well, you've done it. You've (at least for the purposes of this
2231     HOWTO) designed, built, and released your free software
2232     project. All that is left is for you to tell the world so they
2233     know to come and try it out and hopefully jump on board with
2234     development. If everything is in order as described above, this
2235     will be a quick and painless process. A quick announcement is all
2236     that it takes to put yourself on the free software communities
2237     radar screen.
2238    </para>
2239
2240    <sect3>
2241     <title>Mailing lists and USENET</title>
2242     <para>
2243      Email is still the way that most people on the Internet get their
2244      information. Its a good idea to send a message announcing your
2245      program to any relevant mailing list you know of and any relevant
2246      USENET discussion group. Karl Fogel recommends that use you
2247      simple subject describing the fact that the message is an
2248      announcement, the name of the program, the version, and a
2249      half-line long description of its functionality. This way, any
2250      interested user or developer will be immediately attracted to
2251      your announcement. Fogel's example looks like:
2252     </para>
2253
2254     <screen>Subject: ANN: aub 1.0, a program to assemble USENET binaries</screen>
2255
2256     <para>
2257      The rest of the email should describe the programs functionality
2258      quickly and concisely in no more than two paragraphs and should
2259      provide links to the projects webpage and direct links to
2260      downloads for those that want it right away.
2261     </para>
2262
2263     <para>
2264      You should repeat this announcement process consistently in the
2265      same locations for each subsequent release.
2266     </para>
2267    </sect3>
2268
2269    <sect3>
2270     <title>freshmeat.net</title>
2271     <para>
2272      Mentioned earlier in <xref linkend="evalwhere">, in today's free
2273      software community, announcements of your project on freshmeat
2274      are almost more important than announcements on mailing list
2275      announcements.
2276     </para>
2277
2278     <para>
2279      Visit the <ulink url="http://freshmeat.net">freshmeat
2280      website</ulink> or their <ulink
2281      url="http://freshmeat.net/add-project/">submit project
2282      page</ulink> to post your project on their site and in their
2283      database. In addition to a large website, freshmeat provides a
2284      daily newsletter that highlights all the days releases and
2285      reaches a huge audience (I skim it every night for any
2286      interesting new releases).
2287     </para>
2288
2289     <para>
2290      Once you've finished this...
2291     </para>
2292
2293     <para>
2294      Congratulations. You've now the maintainer of an active free
2295      software project. Good luck and feel free to stay in touch with
2296      me about your experiences. I'd love to incorporate them into this
2297      HOWTO.
2298     </para>
2299    </sect3>
2300   </sect2>
2301 </sect1>
2302
2303 </article>
2304
2305 <!-- Keep this comment at the end of the file
2306 Local variables:
2307 mode: sgml
2308 sgml-omittag:t
2309 sgml-shorttag:t
2310 sgml-namecase-general:t
2311 sgml-general-insert-case:lower
2312 sgml-minimize-attributes:nil
2313 sgml-always-quote-attributes:t
2314 sgml-indent-step:1
2315 sgml-indent-data:nil
2316 sgml-parent-document:nil
2317 sgml-exposed-tags:nil
2318 sgml-local-catalogs:nil
2319 sgml-local-ecat-files:nil
2320 End:
2321 -->

Benjamin Mako Hill || Want to submit a patch?