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

Benjamin Mako Hill || Want to submit a patch?