]> projects.mako.cc - fspm_howto/blob - FreeSoftwareDevelopmentHOWTO.sgml
Only small changes and fixes. I also removed all the samples and
[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 something unique
396    </para>
397
398   </sect2>
399
400 <!-- Section2: chooselicense-->
401
402   <sect2 id="chooselicense">
403    <title>Deciding on a License</title>
404    <para></para>
405   </sect2>
406
407 <!-- Section2: chooseversioning-->
408
409   <sect2 id="chooseversioning">
410    <title>Choosing a Method of Version Numbering</title>
411    <para></para>
412   </sect2>
413
414 <!-- Section2: documentation-->
415
416   <sect2 id="documentation">
417    <title>Documentation</title>
418    <para></para>
419   </sect2>
420
421 <!-- Section2: presentation -->
422
423   <sect2 id="presentation">
424    <title>Other Presentation Issues</title>
425    <para></para>
426   </sect2>
427
428 <!-- Section2: futuredev -->
429
430   <sect2 id="futuredev">
431    <title>Nuturing Future Development</title>
432    <para></para>
433   </sect2>
434
435  </sect1>
436
437 <!-- Section1: starting: END -->
438
439 <!-- Section1: developers -->
440
441  <sect1 id="developers">
442   <title>Maintaining a Project: Interacting with Developers</title>
443
444    <indexterm>
445     <primary>fswd!developers</primary>
446    </indexterm>
447
448 <!-- Section2: delegation  -->
449
450   <sect2 id="delegation">
451    <title>Delegating Work</title>
452    <para></para>
453   </sect2>
454
455 <!-- Section2: branches  -->
456
457   <sect2 id="branches">
458    <title>Stable and Development Branches</title>
459    <para></para>
460   </sect2>
461
462 <!-- Section2: freezing -->
463
464   <sect2 id="freezing">
465    <title>Freezing</title>
466    <para></para>
467   </sect2>
468
469 <!-- Section2: codecram -->
470
471   <sect2 id="codecram">
472    <title>Avoiding the Code Cram Effect</title>
473    <para></para>
474   </sect2>
475
476 <!-- Section2: patching -->
477
478   <sect2 id="patching">
479    <title>Accepting and Rejecting Patches</title>
480    <para></para>
481   </sect2>
482  </sect1>
483
484 <!-- Section1: users -->
485
486  <sect1 id="users">
487   <title>Maintaining a Project: Interacting with Users</title>
488
489    <indexterm>
490     <primary>fswd!users</primary>
491    </indexterm>
492
493
494 <!-- Section2: announcing  -->
495
496   <sect2 id="announcing">
497    <title>Announcing Your Project</title>
498    <para></para>
499   </sect2>
500
501 <!-- Section2: testing -->
502
503   <sect2 id="testing">
504    <title>Testing and Testers</title>
505    <para></para>
506   </sect2>
507 </sect1>
508
509 </article>
510
511 <!-- Keep this comment at the end of the file
512 Local variables:
513 mode: sgml
514 sgml-omittag:t
515 sgml-shorttag:t
516 sgml-namecase-general:t
517 sgml-general-insert-case:lower
518 sgml-minimize-attributes:nil
519 sgml-always-quote-attributes:t
520 sgml-indent-step:1
521 sgml-indent-data:nil
522 sgml-parent-document:nil
523 sgml-exposed-tags:nil
524 sgml-local-catalogs:nil
525 sgml-local-ecat-files:nil
526 End:
527 -->

Benjamin Mako Hill || Want to submit a patch?