]> projects.mako.cc - fspm_howto/blob - FreeSoftwareDevelopmentHOWTO.sgml
8c83f39357851277b0acc5ddf0f583c74fe234e4
[fspm_howto] / FreeSoftwareDevelopmentHOWTO.sgml
1 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
2
3 <article>
4
5 <!-- Header -->
6
7  <artheader>
8   <title>Free Software Development HOWTO</title>
9
10   <author>
11      <firstname>Benjamin</firstname>
12      <othername>Mako</othername>
13      <surname>Hill</surname>
14      <affiliation>
15         <address>
16            <email>mako@debian.org</email>
17
18         </address>
19      </affiliation>
20   </author>
21
22    <revhistory>
23       <revision>
24          <revnumber>v0.01</revnumber>
25          <date>25 March 2001</date>
26          <authorinitials>bch</authorinitials>
27           <revremark>
28           Initial Release
29          </revremark>
30       </revision>
31    </revhistory>
32
33   <abstract>
34     <indexterm>
35       <primary>fswd</primary>
36     </indexterm>
37
38     <para>
39      This HOWTO is designed for people with experience in programming
40      and some skills in managing a software project but who are new to
41      the world of Free Software. This document is meant to act as a
42      guide to the non-technical aspects of programming and was written
43      to act as a crash course in the people skills that aren't taught
44      to commercial coders but that can make or break a free software
45      project.
46     </para>
47   </abstract>
48
49  </artheader>
50
51 <!-- Section1: intro -->
52
53  <sect1 id="intro">
54    <title>Introduction</title>
55
56    <indexterm>
57     <primary>fswd!introduction</primary>
58    </indexterm>
59
60   <para>
61    For various reasons, this realease has been codenamed the
62    <emphasis>homade yogurt</emphasis> release.
63   </para>
64
65   <para>
66    New code names will appear as per industry standard
67    guidelines to emphasize the state-of-the-art-ness of this
68    document.
69   </para>
70
71   <para>
72    Skimming through Freshmeat provides mountains of reasons for this
73    HOWTO's existence--the Internet is littered with excellently
74    written and useful programs that have faded away into the Universe
75    of Free Software Forgottenness. This dismal scene made me ask
76    myself, "Why?"
77   </para>
78
79   <para>
80    This HOWTO tries to do a lot of thing (probably too many), but it
81    can't answer that question and won't attempt it. What this HOWTO
82    will attempt to do is give your Free Software project a fighting
83    chance-an edge. If you write a piece of crap that no one is
84    interested in, you can read this HOWTO until you recite it in your
85    sleep and your project will probably fail. Then again, you can
86    write a beautiful, relevent piece of software and follow every
87    instruction in this HOWTO and your software may still not make
88    it. Sometimes life is like that. However, I'll go out a limb and
89    say that if you write a great, relevant pieces of software and
90    ignore the advise in this HOWTO, you'll probably fail <emphasis>
91    more often</emphasis>.
92   </para>
93
94   <para>
95    A lot of the information in this HOWTO is best called common
96    sense. Of course, as any debate on interfaces will prove, what is
97    common sense to some programmers proves totally unintuitive to
98    others. After explaining bites and pieces of this HOWTO to Free
99    Software developers on several occasions, I realized that that
100    writing this HOWTO might provide a useful resource and a forum for
101    programmers to share ideas about what has and has not worked for
102    them. 
103   </para>
104
105   <para>
106
107   </para>
108
109   <para>
110    As anyone involved in any of what seems like an unending parade of
111    ridiculous intellectual property clashes will attest to, a little
112    bit of legalese proves important.
113   </para>
114
115 <!-- Section2: copyright -->
116
117   <sect2 id="copyright">
118    <title>Copyright Information</title>
119
120    <para>
121     This document is copyrighted (c) 2000 Benjamin (Mako) Hill and is
122     distributed under the terms of the Linux Documentation Project
123     (LDP) license, stated below.
124    </para>
125
126    <para>
127     Unless otherwise stated, Linux HOWTO documents are
128     copyrighted by their respective authors. Linux HOWTO documents may
129     be reproduced and distributed in whole or in part, in any medium
130     physical or electronic, as long as this copyright notice is
131     retained on all copies. Commercial redistribution is allowed and
132     encouraged; however, the author would like to be notified of any
133     such distributions.
134    </para>
135
136    <para>
137     All translations, derivative works, or aggregate works
138     incorporating any Linux HOWTO documents must be covered under this
139     copyright notice. That is, you may not produce a derivative work
140     from a HOWTO and impose additional restrictions on its
141     distribution. Exceptions to these rules may be granted under
142     certain conditions; please contact the Linux HOWTO coordinator at
143     the address given below.
144    </para>
145
146    <para>
147     In short, we wish to promote dissemination of this
148     information through as many channels as possible. However, we do
149     wish to retain copyright on the HOWTO documents, and would like to
150     be notified of any plans to redistribute the HOWTOs.
151    </para>
152
153    <para>
154     If you have any questions, please contact 
155     <email>linux-howto@metalab.unc.edu</email>
156    </para>
157   </sect2>
158
159 <!-- Section2: disclaimer -->
160
161   <sect2 id="disclaimer">
162    <title>Disclaimer</title>
163
164    <para>
165     No liability for the contents of this documents can be accepted.
166     Use the concepts, examples and other content at your own risk.
167     As this is a new edition of this document, there may be errors
168     and inaccuracies, that may of course be damaging to your system.
169     Proceed with caution, and although this is highly unlikely,
170     the author(s) do not take any responsibility for that.
171    </para>
172
173    <para>
174     All copyrights are held by their by their respective owners, unless
175     specifically noted otherwise.  Use of a term in this document
176     should not be regarded as affecting the validity of any trademark
177     or service mark.
178    </para>
179
180    <para>
181     Naming of particular products or brands should not be seen 
182     as endorsements.
183    </para>
184
185    <para>
186     You are strongly recommended to take a backup of your system 
187     before major installation and backups at regular intervals.
188    </para>
189   </sect2>
190
191 <!-- Section2: newversions-->
192
193   <sect2 id="newversions">
194    <title>New Versions</title>
195
196     <indexterm>
197      <primary>(your index root)!news on</primary>
198     </indexterm>
199
200    <para>
201     This is the initial release. It is written to be released to
202     developers for critique and brainstorming and submitted to
203     Hampshire College for academic credit. Please keep in mind that
204     this version of the HOWTO is still in an infant stage and will be
205     revised extensively before it hits the LDP.
206    </para>
207
208    <para>
209     The latest version number of this document should always be listed 
210     at my webpage at<ulink url="http://people.debian.org/~mako/">
211     http://people.debian.org/~mako/</ulink> Debian.
212    </para>
213
214    <para>
215     The newest version of this HOWTO will always be made available at
216     the same website, in a variety of formats:
217    </para>
218
219    <para>
220    <itemizedlist>
221     <listitem>
222      <para>
223       <ulink url="http://people.debian.org/~mako/howto/fswd-howto.html">HTML</ulink>.
224      </para>
225     </listitem>
226
227     <listitem>
228      <para>
229        <ulink URL="http://people.debian.org/~mako/howto/fswd-howto.txt">plain text</ulink>.
230      </para>
231     </listitem>
232
233     <listitem>
234      <para>
235       <ulink url="http://people.debian.org/~mako/howto/fswd-howto.US.ps.gz">compressed 
236        postscript (US letter format)</ulink>.
237      </para>
238     </listitem>
239
240     <listitem>
241      <para>
242       <ulink url="http://people.debian.org/~mako/howto/fswd-howto.UF.ps.gz">compressed 
243        postscript (Universal format / 8.27x11in; 210x279mm)</ulink>.
244      </para>
245     </listitem>
246
247     <listitem>
248      <para>
249       <ulink url="http://people.debian.org/~mako/howto/fswd-howto.sgml">SGML source</ulink>.
250      </para>
251     </listitem>
252    </itemizedlist>
253    </para>
254   </sect2>
255
256 <!-- Section2: credits -->
257
258   <sect2 id="credits">
259    <title>Credits</title>
260
261    <para>
262     In this version I have the pleasure of acknowledging:
263    </para>
264
265    <para>
266     <emphasis>Karl Fogel</emphasis>, the author of <emphasis>Open
267     Source Development with CVS</emphasis> published by the Coriolis
268     Open Press. Larges parts of the book are available <ulink
269     url="http://cvsbook.red-bean.com">on the web</ulink>. 225 pages of
270     the book are available under the GPL and constitute the best
271     tutorial on CVS I have ever seen. The rest of the book covers,
272     "the challenges and philosophical issues inherent in running an
273     Open Source project using CVS." The book does a good job of
274     covering some of the subjects brought up in this HOWTO and much
275     more. <ulink url="http://cvsbook.red-bean.com">The book's
276     website</ulink> has information on ordering the book and provides
277     several translations of the chapters on CVS. I you are seriously
278     interested in running a Free Software project, you want this book.
279    </para>
280    
281    <para>
282     Karl Fogel can be reached at <email>kfogel (at) red-bean (dot)
283     com</email>
284    </para>
285    <para>
286     Also providing support and material, and inspiration for this
287     HOWTO is Eric S. Raymond for his prolific, consitent, and
288     carefully crafted arguments, to Lawrence Lessig for reminding me
289     of the importance of Free Software and to every user and developer
290     involved with the <ulink url="http://www.debian.org">Debian
291     Project</ulink>. The project has provided me with a home, a place
292     to practice Free Software advocacy and to make a difference, a
293     place to learn from those how have been involved with the movement
294     much longer than I, and an proof of a Free Software project that
295     <emphasis>definately, definately works</emphasis>.
296    </para>
297
298    <para>
299     Above all, I want to thank <emphasis>Richard Stallman</emphasis>
300     for his work at the Free Software Foundation and for never giving
301     up. Stallman provided the philosphical basis that attracts me to
302     Free Software and that drives me towards writing a document to
303     make sure it succeeds. RMS can always be emailed at <email>rms
304     (at) gnu (dot) org</email>.
305    </para>
306
307   </sect2>
308
309 <!-- Section2: feedback -->
310
311   <sect2 id="feedback">
312    <title>Feedback</title>
313
314    <para>
315     Feedback is most certainly welcome for this document. Without your
316     submissions and input, this document wouldn't exist. Something
317     missing? Don't hesitate to contact me and to write a chapter. I
318     want this document to be as much a product of the Free Software
319     development process that it heralds and I think its ultimate
320     success will be rooted in this fact. Please send your additions,
321     comments and criticisms to the following email address :
322     <email>mako (at) debian (dot) org</email>.
323    </para>
324    </sect2>
325
326 <!-- Section2: translations -->
327
328   <sect2 id="translations">
329    <title>Translations</title>
330
331    <para>
332     I know that not everyone speaks English. Translations are nice and
333     I'd love for this HOWTO to gain the kind of international reach
334     afforded by a translated version.
335    </para>
336    <para>
337     However, this HOWTO is still young and I have to yet to be
338     contacted about a translation so English is all that is
339     available. If you would like to help with or do a translation, you
340     will gain my utmost respect and admiration and you'll get to be
341     part of a cool process. If you are at all interested, please don't
342     hesitate to contact me at: <email>mako (at) debian (dot)
343     org</email>.
344    </para>
345    </sect2>
346  </sect1>
347
348 <!-- Section1: intro: END -->
349
350 <!-- Section1: starting -->
351
352  <sect1 id="starting">
353   <title>Starting a Project</title>
354
355    <indexterm>
356     <primary>fswd!starting</primary>
357    </indexterm>
358   <para>
359    With very little argument, starting a project is most difficult
360    part of successful free software development. Laying a firm
361    foundation for your project will determine whether your project
362    flourishes or withers away and dies. It is also the subject that is
363    of most immediate interest to anyone reading this document as a
364    tutorial.
365   </para>
366
367   <para>
368    Starting a project also involves a dilemna that you as a developer
369    must try and deal with. No potential user for your program will be
370    interested by a program that doesn't work. Simultaneously, the
371    development process that you want to employ holds involvement of
372    users as essential to the process of the development that will
373    realize this working software.
374   </para>
375
376   <para>
377    It is in these dangerous initial moments that anyone working to
378    start a free software project must strike a balance. One of the
379    most important ways that omeone trying to start a project can work
380    towards this balance is by establishing a framework for the
381    development process through some of the ways mentioned in this
382    section.
383   </para>
384
385
386 <!-- Section2: chooseproject-->
387
388   <sect2 id="chooseproject">
389    <title>Choosing a Project</title>
390
391    <para>
392     If you are reading this document, there's a good chance you
393     already have an idea for a project in mind. Chances are pretty
394     good, it fills a gap by doing something that no other free
395     software process does or or does it in a way that is unique
396     enought to necessitate a seperate project.
397    </para>
398
399    <sect3 id=identifyidea>
400     <title>Indentify and Articulate Your Idea</title>
401     <para>
402      Eric S. Raymond writes about how free software projects start in
403      his paper, "The Cathedral and the Bazaar" which comes as required
404      reading for any free softare development. You can find it online
405      at <ulink url="http://www.tuxedo.org/!esr/writings/cathedral-bazaar/">
406      http://www.tuxedo.org/!esr/writings/cathedral-bazaar/</ulink>.
407     </para>
408
409     <para>
410      In "The Cathedral and Bazaar," Raymond tells us that:
411      <emphasis>Every good work of software starts by scratching a
412      developers itch.</emphasis> Raymond now widely accepted
413      hypothesis is that new free software programs are written, first
414      and foremost, to solve a specific problem facing the developer.
415     </para>
416
417     <para>
418      If you have an idea for a program in mind, chances are good that
419      it it is targetting a specific problem or itch you want to see
420      scratched. <emphasis>This idea is the project. Articulate it
421      clearly. Write it out. Describe the problem you will attack in
422      detail. The success of your project in tackling a particular
423      problem will be tied to your ability to identify that problem
424      early on. Find out exactly what it is that you want your project
425      to do.</emphasis>
426     </para>
427    </sect3>
428
429    <sect3 id=evalulateidea>
430     <title>Evaluate Your Idea</title>
431
432     <para>
433      In evaluating your idea, you need to ask yourself questions.
434      Before you move any further into this HOWTO, you need to
435      determine if the free software development model really is the
436      right one for your project. Obviously, since the program
437      scratches your itch, you are definately interested in seeing it
438      implemented in code. But, because one hacker coding alone fails
439      to qualify as a free software development effort, you need to ask
440      yourself the question: <emphasis>Is anybody else
441      interested?</emphasis>
442     </para>
443
444     <para>
445      Sometimes the answer is <emphasis>no</emphasis>. If you want to
446      write a set of scripts to sort <emphasis>your</emphasis> MP3
447      collection on your machine, maybe the free software development
448      model is not the best one to choose. However, if you want to
449      write a set of scripts to sort <emphasis>anyone's</emphasis>
450      MP3s, a free software project might fill a useful gap.
451     </para>
452
453     <para>
454      Luckily, The Internet is a place so big and diverse that, chances
455      are, there is someone, somewhere, who shares your interests and
456      how feels the same itch. It is the fact that there are so many
457      people with so many similar needs and desires that introduces the
458      second major question: <emphasis>Has somebody already had your
459      idea or a reasonably similar one?</emphasis>
460     </para>
461
462      <sect4 id=evalwhere>
463       <title>Finding Similar Projects</title>
464
465      <para>
466       There are places you can go on the web to try and answer this
467       question. If you have experience with the free software
468       community, you are probably already familiar with all of these
469       sites. All of the resources listed bellow offer searching of
470       their databases:
471      </para>
472
473      <para>
474      <variablelist>
475        <varlistentry>
476         <term>freshmeat.net</term>
477         <listitem>
478          <para>
479           Located at at <ulink url="http://freshmeat.net">
480           http://freshmeat.net</ulink>, freshmeat describes itself as,
481           <quote>the Web's largest index of Linux and Open Source
482           software</quote> and its reputation along these lines remains
483           unquestioned. If you can't find it on freshmeat, its doubtful
484           that you'll find it indexed anywhere else.
485          </para>
486         </listitem>
487        </varlistentry>
488
489        <varlistentry>
490         <term>Slashdot</term>
491         <listitem>
492          <para>
493           Located at <ulink url="http://slashdot.org">
494           http://slashdot.org</ulink>, Slashdot provides <quote>News
495           for Nerds: Stuff that Matters,</quote> which usually includes
496           discussion of free software, open source, technology, and
497           geek culture new and events. It is not unusual for an
498           particularly sexy develpment effort to be announced here so
499           it definately worth checking.
500          </para>
501         </listitem>
502        </varlistentry>
503
504        <varlistentry>
505         <term>SourceForge</term>
506         <listitem>
507          <para>
508           Located at <ulink url="http://sourceforge.net">
509           http://sourceforge.net</ulink>, SourceForge houses and
510           facilitates a growning number of open source and free
511           software projects, SourceForge is quickly becoming a nexus
512           and an necessary stop for free software
513           developers. SourceForge's 
514           <ulink url="http://sourceforge.net/softwaremap/trove_list.php">
515           software map</ulink> and <ulink
516           url="http://sourceforge.net/new/"> new releases</ulink>
517           pages. should be necessary stops before embarking on a new
518           free software project. SourceForge also provides a
519           <emphasis>Code Snippet Library</emphasis> at <ulink
520           url="http://sourceforge.net/snippet/">http://sourceforge.net/snippet/</ulink>
521           which contains useful reusuable chunks of code in an array
522           of langauges which can come in useful in any project.
523          </para>
524         </listitem>
525        </varlistentry>
526
527        <varlistentry>
528         <term>Google and Google's Linux Search</term>
529         <listitem>
530          <para>
531           Located at <ulink url="http://www.google.com">
532           http://www.google.com</ulink> and
533           <ulink url="http://www.google.com/linux">
534           http://www.google.com/linux</ulink>, provide prowerful web
535           searches that may reveal people working on similar
536           projects. It is not a catalog of software or news like
537           freshmeat or Slashdot, but it is worth checking before you
538           begin pouring your effort into a redundant project.
539          </para>
540         </listitem>
541        </varlistentry>
542
543       </variablelist>
544      </para>
545     </sect4>
546
547     <sect4 id=evalhow>
548      <title>Deciding to Proceed</title>
549      <para>
550       Once you have successfull charted the terrain and have an idea
551       bout what kinds of similar free software projects exist, every
552       developer needs to decide whether to proceed with their own
553       project. It is rare that a new project seeks to accomplish a
554       goal that is not similar to related to the goal of another
555       project. Anyone starting a new project needs to ask themselves:
556       <emphasis>Will the new project be duplicating work done by
557       another project? Will the new project be competing for
558       developers with an existing project? Can the goals of the new
559       project be accomplished by adding functionality to an existing
560       project?</emphasis>
561      </para>
562
563      <para>
564       If the answer to any of these questions is yes, try to contact
565       the developer of the existing project in question and see if he
566       or she might be willing to collaborate with you.
567      </para>
568
569      <para>
570       This may be the single most difficult aspect of free software
571       development for many developers but it is essential. It is easy
572       to become fired up by and idea and be caught up in the momentum
573       and excitement of a new project. It is often extremely difficult
574       but it is important that any free software developer rememeber
575       that the best interests of the of the free software community
576       and the quickest way to accomplish ones own project's goals and
577       the goals of similar project can often be accomplished by
578       <emphasis>not</emphasis> starting a new project.
579      </para>
580
581     </sect4>
582    </sect3>
583   </sect2>
584
585 <!-- Section2: chooselicense-->
586
587   <sect2 id="chooselicense">
588    <title>Deciding on a License</title>
589    <para></para>
590   </sect2>
591
592 <!-- Section2: chooseversioning-->
593
594   <sect2 id="chooseversioning">
595    <title>Choosing a Method of Version Numbering</title>
596    <para></para>
597   </sect2>
598
599 <!-- Section2: documentation-->
600
601   <sect2 id="documentation">
602    <title>Documentation</title>
603    <para></para>
604   </sect2>
605
606 <!-- Section2: presentation -->
607
608   <sect2 id="presentation">
609    <title>Other Presentation Issues</title>
610    <para></para>
611   </sect2>
612
613 <!-- Section2: futuredev -->
614
615   <sect2 id="futuredev">
616    <title>Nuturing Future Development</title>
617    <para></para>
618   </sect2>
619
620  </sect1>
621
622 <!-- Section1: starting: END -->
623
624 <!-- Section1: developers -->
625
626  <sect1 id="developers">
627   <title>Maintaining a Project: Interacting with Developers</title>
628 ></ulink>which
629    <indexterm>
630     <primary>fswd!developers</primary>
631    </indexterm>
632
633 <!-- Section2: delegation  -->
634
635   <sect2 id="delegation">
636    <title>Delegating Work</title>
637    <para></para>
638   </sect2>
639
640 <!-- Section2: branches  -->
641
642   <sect2 id="branches">
643    <title>Stable and Development Branches</title>
644    <para></para>
645   </sect2>
646
647 <!-- Section2: freezing -->
648
649   <sect2 id="freezing">
650    <title>Freezing</title>
651    <para></para>
652   </sect2>
653
654 <!-- Section2: codecram -->
655
656   <sect2 id="codecram">
657    <title>Avoiding the Code Cram Effect</title>
658    <para></para>
659   </sect2>
660
661 <!-- Section2: patching -->
662
663   <sect2 id="patching">
664    <title>Accepting and Rejecting Patches</title>
665    <para></para>
666   </sect2>
667  </sect1>
668
669 <!-- Section1: users -->
670
671  <sect1 id="users">
672   <title>Maintaining a Project: Interacting with Users</title>
673
674    <indexterm>
675     <primary>fswd!users</primary>
676    </indexterm>
677
678
679 <!-- Section2: announcing  -->
680
681   <sect2 id="announcing">
682    <title>Announcing Your Project</title>
683    <para></para>
684   </sect2>
685
686 <!-- Section2: testing -->
687
688   <sect2 id="testing">
689    <title>Testing and Testers</title>
690    <para></para>
691   </sect2>
692 </sect1>
693
694 </article>
695
696 <!-- Keep this comment at the end of the file
697 Local variables:
698 mode: sgml
699 sgml-omittag:t
700 sgml-shorttag:t
701 sgml-namecase-general:t
702 sgml-general-insert-case:lower
703 sgml-minimize-attributes:nil
704 sgml-always-quote-attributes:t
705 sgml-indent-step:1
706 sgml-indent-data:nil
707 sgml-parent-document:nil
708 sgml-exposed-tags:nil
709 sgml-local-catalogs:nil
710 sgml-local-ecat-files:nil
711 End:
712 -->

Benjamin Mako Hill || Want to submit a patch?