2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
9 <title>Free Software Project Management HOWTO</title>
12 <firstname>Benjamin</firstname>
13 <othername>Mako</othername>
14 <surname>Hill</surname>
17 <email>mako@atdot.cc</email>
24 <revnumber>v0.3.3</revnumber>
25 <date>22 August 2008</date>
26 <authorinitials>bmh</authorinitials>
30 <revnumber>v0.3.2</revnumber>
31 <date>15 April 2002</date>
32 <authorinitials>bmh</authorinitials>
36 <revnumber>v0.3.1</revnumber>
37 <date>18 June 2001</date>
38 <authorinitials>bmh</authorinitials>
42 <revnumber>v0.3</revnumber>
43 <date>5 May 2001</date>
44 <authorinitials>bmh</authorinitials>
48 <revnumber>v0.2.1</revnumber>
49 <date>10 April 2001</date>
50 <authorinitials>bmh</authorinitials>
54 <revnumber>v0.2</revnumber>
55 <date>8 April 2001</date>
56 <authorinitials>bmh</authorinitials>
60 <revnumber>v0.01</revnumber>
61 <date>27 March 2001</date>
62 <authorinitials>bmh</authorinitials>
63 <revremark>Initial Release</revremark>
69 <primary>fswd</primary>
73 This HOWTO is designed for people with experience in programming
74 and some skills in managing a software project but who are new to
75 the world of free software. This document is meant to act as a
76 guide to the non-technical aspects of free software project
77 management and was written to be a crash course in the people
78 skills that aren't taught to commercial coders but that can make
79 or break a free software project.
85 <!-- Section1: intro -->
88 <title>Introduction</title>
91 <primary>fswd!introduction</primary>
95 Skimming through freshmeat.net provides mountains of reasons for this
96 HOWTO's existence--the Internet is littered with excellently
97 written and useful programs that have faded away into the universe
98 of free software forgottenness. This dismal scene made me ask
103 This HOWTO tries to do a lot of things (probably too many), but it
104 can't answer that question and won't attempt it. What this HOWTO
105 will attempt to do is give your Free Software project a fighting
106 chance--an edge. If you write a piece of crap that no one is
107 interested in, you can read this HOWTO until you can recite it in
108 your sleep and your project will probably fail. Then again, you can
109 write a beautiful, relevant piece of software and follow every
110 instruction in this HOWTO and your software may still not make
111 it. Sometimes life is like that. However, I'll go out a limb and
112 say that if you write a great, relevant pieces of software and
113 ignore the advise in this HOWTO, you'll probably fail <emphasis>
114 more often</emphasis>.
118 A lot of the information in this HOWTO is best called common
119 sense. Of course, as any debate on interfaces will prove, what is
120 common sense to some programmers proves totally unintuitive to
121 others. After explaining bits and pieces of this HOWTO to Free
122 Software developers on several occasions, I realized that writing
123 this HOWTO might provide a useful resource and a forum for
124 programmers to share ideas about what has and has not worked for
129 As anyone involved in any of what seems like an unending parade of
130 ridiculous intellectual property clashes will attest to, a little
131 bit of legalese proves important.
134 <!-- Section2: copyright -->
136 <sect2 id="copyright">
137 <title>Copyright Information</title>
140 This document is copyrighted (c) 2000-2008 Benjamin Mako Hill and is
141 distributed under the terms of the <citetitle>GNU Free
142 Documentation License</citetitle>.
146 Permission is granted to copy, distribute and/or modify this
147 document under the terms of the <link
148 linkend="fdl"><citetitle>GNU Free Documentation
149 License</citetitle></link>, Version 1.2 or any later version
150 published by the Free Software Foundation with no Invariant
151 Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy
152 of the license can be found in <xref linkend="fdl">.
156 <!-- Section2: disclaimer -->
158 <sect2 id="disclaimer">
159 <title>Disclaimer</title>
162 No liability for the contents of this documents can be accepted.
163 Use the concepts, examples and other content at your own risk. As
164 this is a new edition of this document, there may be errors and
165 inaccuracies, that may of course be damaging to your project (and
166 potentially your system). Proceed with caution, and although this
167 is highly unlikely, the author(s) does not take any responsibility
172 All copyrights are held by their by their respective owners, unless
173 specifically noted otherwise. Use of a term in this document
174 should not be regarded as affecting the validity of any trademark
179 Naming of particular products or brands should not be seen
185 <!-- Section2: newversions-->
187 <sect2 id="newversions">
188 <title>New Versions</title>
191 This version is the part of the third pre-release cycle of this
192 HOWTO. It is written to be released to developers for critique and
193 brainstorming. While the HOWTO is now several years old, please keep
194 in mind that this version of the HOWTO is still in an "early" stage
195 and will continue to be revised extensively.
199 The latest version number of this document should always be listed
200 on <ulink url="http://mako.cc/projects/howto">the projects
205 The newest version of this HOWTO will always be made available at
206 the same website, in a variety of formats:
214 <ulink url="http://mako.cc/projects/howto/FreeSoftwareProjectManagement-HOWTO/t1.html">HTML</ulink>.
221 <ulink url="http://mako.cc/projects/howto/FreeSoftwareProjectManagement-HOWTO.html">HTML (single page)</ulink>.
227 <ulink URL="http://mako.cc/projects/howto/FreeSoftwareProjectManagement-HOWTO.txt">plain text</ulink>.
233 <ulink url="http://mako.cc/projects/howto/FreeSoftwareProjectManagement-HOWTO.ps.gz">Compressed postscript</ulink>.
239 <ulink url="http://mako.cc/projects/howto/FreeSoftwareProjectManagement-HOWTO.sgml.gz">Compressed SGML source</ulink>.
246 <!-- Section2: credits -->
249 <title>Credits</title>
252 In this version I have the pleasure of acknowledging:
255 <para>Fellow Debian developers Martin Michlmayr and Vivek
256 Venugopalan who sent me information and links to extremely
257 interesting articles. I've added both to the bibliography and I've
258 added information from each into the HOWTO. Thanks to Andrew Shugg
259 who pointed out several errors in the document. Also, a big thanks
260 to Sung Wook Her (AKA RedBaron) who is doing the first translation
261 of the HOWTO into Korean. I've been happy to see that people have
262 enjoyed and benefited from the HOWTO so far.</para>
265 Older thanks that I don't want to take out yet include: Josh
266 Crawford, Andy King, and Jaime Davila who all read through this in
267 entirety and gave me feedback that has helped me make changes and
268 improvements to this document. I can't thank you guys enough for
269 your help. An extra <quote>Thank You</quote> goes to Andy King who
270 who read through this several times and submitted patches to make
275 Karl Fogel, the author of <citetitle>Open Source Development with
276 CVS</citetitle> published by the Coriolis Open Press. Large parts
277 of his book are available <ulink
278 url="http://cvsbook.red-bean.com">on the web</ulink>. 225 pages of
279 the book are available under the GPL and constitute the best
280 tutorial on CVS I've ever seen. The rest of the book covers,
281 <quote>the challenges and philosophical issues inherent in running
282 an Open Source project using CVS.</quote> The book does a good job
283 of covering some of the subjects brought up in this HOWTO and much
284 more. <ulink url="http://cvsbook.red-bean.com">The book's
285 website</ulink> has information on ordering the book and provides
286 several translations of the chapters on CVS. If you are seriously
287 interested in running a Free Software project, you want this
288 book. I tried to mention Fogel in sections of this HOWTO where I
289 knew I was borrowing directly from his ideas. If I missed any, I'm
290 sorry. I'll try and have those fixed in future versions.
294 Karl Fogel can be reached at <email>kfogel (at) red-bean (dot)
299 Also providing support material, and inspiration for this HOWTO is
300 Eric S. Raymond for his prolific, consistent, and carefully
301 crafted arguments and Lawrence Lessig for reminding me of the
302 importance of Free Software. Additionally, I want to thank every
303 user and developer involved with the <ulink
304 url="http://www.debian.org">Debian Project</ulink>. The project
305 has provided me with a home, a place to practice free software
306 advocacy, a place to make a difference, a place to learn from
307 those who have been involved with the movement much longer than I,
308 and proof of a free software project that definitely, definitely
313 Above all, I want to thank <emphasis>Richard Stallman</emphasis>
314 for his work at the Free Software Foundation and for never giving
315 up. Stallman provides and articulates the philosophical basis that
316 attracts me to free software and that drives me toward writing a
317 document to make sure it succeeds. RMS can always be emailed at
318 <email>rms (at) gnu (dot) org</email>.
323 <!-- Section2: feedback -->
325 <sect2 id="feedback">
326 <title>Feedback</title>
329 Feedback is always and most certainly welcome for this
330 document. Without your submissions and input, this document
331 wouldn't exist. Do you feel that something is missing? Don't
332 hesitate to contact me to have me write a chapter, section, or
333 subsection or to write one yourself. I want this document to be a
334 product of the Free Software development process that it heralds
335 and I believe that its ultimate success will be rooted in its
336 ability to do this. Please send your additions, comments, and
337 criticisms to the following email address:
338 <email>mako@atdot.cc</email>.
342 <!-- Section2: translations -->
344 <sect2 id="translations">
345 <title>Translations</title>
348 I know that not everyone speaks English. Translations are nice and
349 I'd love for this HOWTO to gain the kind of international reach
350 afforded by translated versions.
354 This HOWTO has graciously translated into German by Robert F.
355 Schmitt. That copy is accessible in the following formats:
361 <ulink url="http://mako.cc/projects/howto/FreeSoftwareProjectManagement-HOWTO.DE.html">HTML (single page)</ulink>.
367 <ulink url="http://mako.cc/projects/howto/FreeSoftwareProjectManagement-HOWTO.DE.rstl">Restructured Text Source</ulink>.
373 If you would like to help with or do a translation, you will gain my
374 utmost respect and admiration and you'll get to be part of a cool
375 process. If you are at all interested, please don't hesitate to
376 contact me at: <email>mako@atdot.cc</email>.
381 <!-- Section1: intro: END -->
383 <!-- Section1: starting -->
385 <sect1 id="starting">
386 <title>Starting a Project</title>
389 <primary>fswd!starting</primary>
392 With very little argument, the beginning is the most difficult
393 period in a project's life to do successful free software project
394 management. Laying a firm foundation will determine whether your
395 project flourishes or withers away and dies. It is also the subject
396 that is of most immediate interest to anyone reading this document
401 Starting a project involves a dilemma that you as a developer must
402 try and deal with: no potential user for your program is interested
403 in a program that doesn't work, while the development process that
404 you want to employ holds involvement of users as imperative.
408 It is in these dangerous initial moments that anyone working to
409 start a free software project must try and strike a balance along
410 these lines. One of the most important ways that someone trying to
411 start a project can work toward this balance is by establishing a
412 solid framework for the development process through some of the
413 suggestions mentioned in this section.
417 <!-- Section2: chooseproject-->
419 <sect2 id="chooseproject">
420 <title>Choosing a Project</title>
423 If you are reading this document, there's a good chance you
424 already have an idea for a project in mind. Chances are also
425 pretty good that it fills a perceived gap by doing something that
426 no other free software project does or by doing something in a way
427 that is unique enough to necessitate a brand new piece of
431 <sect3 id=identifyidea>
432 <title>Identify and articulate your idea</title>
434 Eric S. Raymond writes about how free software projects start in
436 url="http://catb.org/~esr/writings/cathedral-bazaar/"><quote>The
437 Cathedral and the Bazaar,</quote></ulink> which comes as required
438 reading for any free software developer. It is available online .
442 In <quote>The Cathedral and the Bazaar,</quote> Raymond tells us
443 that: <quote>every good work of software starts by scratching
444 a developers itch.</quote> Raymond's now widely accepted
445 hypothesis is that new free software programs are written, first
446 and foremost, to solve a specific problem facing the developer.
450 If you have an idea for a program in mind, chances are good that
451 it targets a specific problem or <quote>itch</quote> you want to
452 see scratched. <emphasis>This idea is the project.</emphasis>
453 Articulate it clearly. Write it out. Describe the problem you
454 will attack in detail. The success of your project in tackling a
455 particular problem will be tied to your ability to identify that
456 problem clearly early on. Find out exactly what it is that you
457 want your project to do.
461 Monty Manley articulates the importance of this initial step in
462 an essay, <quote><ulink
463 url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
464 Projects the Open Source Way.</ulink></quote> As the next section
465 will show, there is <emphasis>a lot</emphasis> of work that needs
466 to be done before software is even ready to be coded. Manley
467 says, <quote>Beginning an OSS project properly means that a
468 developer must, first and foremost, avoid writing code too
473 <sect3 id=evalulateidea>
474 <title>Evaluate your idea</title>
477 In evaluating your idea, you need to first ask yourself a few
478 questions. This should happen before you move any further
479 through this HOWTO. Ask yourself: <emphasis>Is the free software
480 development model really the right one for your
485 Obviously, since the program scratches your itch, you are
486 definitely interested in seeing it implemented in code. But,
487 because one hacker coding in solitude fails to qualify as a free
488 software development effort, you need to ask yourself a second
489 question: <emphasis>Is anybody else interested?</emphasis>
493 Sometimes the answer is a simple <quote>no.</quote> If you want
494 to write a set of scripts to sort <emphasis>your</emphasis>
495 <acronym>MP3</acronym> collection on <emphasis>your</emphasis>
496 machine, <emphasis>maybe</emphasis> the free software development
497 model is not the best one to choose. However, if you want to
498 write a set of scripts to sort <emphasis>anyone's</emphasis>
499 <acronym>MP3</acronym>s, a free software project might fill a
504 Luckily, the Internet is a place so big and so diverse that,
505 chances are, there is someone, somewhere, who shares your
506 interests and who feels the same <quote>itch.</quote> It is the
507 fact that there are so many people with so many similar needs and
508 desires that introduces the third major question: <emphasis>Has
509 somebody already had your idea or a reasonably similar
514 <title>Finding Similar Projects</title>
517 There are places you can go on the web to try and answer the
518 question above. If you have experience with the free software
519 community, you are probably already familiar with many of these
520 sites. All of the resources listed below offer searching of
527 <term>freshmeat.net</term>
529 <para><ulink url="http://freshmeat.net">freshmeat.net</ulink>
530 describes itself as, <quote>the Web's largest index of Linux
531 and Open Source software</quote> and its reputation along
532 these lines is totally unparalleled and unquestioned. If you
533 can't find it on freshmeat, its doubtful that you (or anyone
534 else) will find it at all.</para>
539 <term>Slashdot</term>
541 <para><ulink url="http://slashdot.org">Slashdot</ulink>
542 provides <quote>News for Nerds. Stuff that matters,</quote>
543 which usually includes discussion of free software, open
544 source, technology, and geek culture news and events. It is
545 not unusual for a particularly sexy development effort to be
546 announced here, so it is definitely worth checking.</para>
551 <term>SourceForge</term>
553 <para><ulink url="http://sourceforge.net">SourceForge</ulink>
554 houses and facilitates a growing number of open source and
555 free software projects. It is also quickly becoming a nexus
556 and a necessary stop for free software
557 developers. SourceForge's <ulink
558 url="http://sourceforge.net/softwaremap/trove_list.php">software
559 map</ulink> and <ulink url="http://sourceforge.net/new/"> new
560 release</ulink> pages should be necessary stops before
561 embarking on a new free software project. SourceForge also
563 url="http://sourceforge.net/snippet/">Code Snippet
564 Library</ulink> which contains useful reusable chunks of code
565 in an array of languages which can come in useful in any
571 <term>Google and Google's Linux Search</term>
573 <para><ulink url="http://www.google.com">Google</ulink> and
574 <ulink url="http://www.google.com/linux"> Google's Linux
575 Search</ulink>, provides powerful web searches that may reveal
576 people working on similar projects. It is not a catalog of
577 software or news like freshmeat or Slashdot, but it is worth
578 checking to make sure you aren't pouring your effort into a
579 redundant project.</para>
588 <title>Deciding to Proceed</title>
590 Once you have successfully charted the terrain and have an idea
591 about what kinds of similar free software projects exist, every
592 developer needs to decide whether to proceed with their own
593 project. It is rare that a new project seeks to accomplish a
594 goal that is not at all similar or related to the goal of
595 another project. Anyone starting a new project needs to ask
596 themselves: <quote>Will the new project be duplicating work done
597 by another project? Will the new project be competing for
598 developers with an existing project? Can the goals of the new
599 project be accomplished by adding functionality to an existing
604 If the answer to any of these questions is <quote>yes,</quote>
605 try to contact the developer of the existing project(s) in
606 question and see if he or she might be willing to collaborate
611 For many developers this may be the single most difficult aspect
612 of free software project management, but it is an essential one. It is
613 easy to become fired up by an idea and get caught up in the
614 momentum and excitement of a new project. It is often extremely
615 difficult to do, but it is important that any free software
616 developer remembers that the best interests of the free software
617 community and the quickest way to accomplish your own project's
618 goals and the goals of similar projects can often be
619 accomplished by <emphasis>not</emphasis> starting a new
627 <!-- Section2: naming-->
630 <title>Naming your project</title>
633 While there are plenty of projects that fail with descriptive
634 names and plenty that succeed without them, I think naming your
635 project is worth giving a bit of thought. Leslie Orchard tackles
636 this issue in an <ulink
637 url="http://www.advogato.org/article/67.html">Advogato
638 article</ulink>. His article is short and definitely worth looking
643 The synopsis is that Orchard recommends you pick a name where,
644 after hearing the name, many users or developers will both:
650 <para>Know what the project does.</para>
653 <para>Remember it tomorrow.</para>
659 Humorously, Orchard's project, <quote>Iajitsu,</quote> does
660 neither. It is probably unrelated that development has effectively
661 frozen since the article was written.
665 He makes a good point though. There are companies whose only job
666 is to make names for pieces of software. They make
667 <emphasis>ridiculous</emphasis> amount of money doing it and are
668 supposedly worth it. While you probably can't afford a company like
669 this, you can afford to learn from their existence and think a
670 little bit about the name you are giving your project because it
671 <emphasis>does</emphasis> matter.
675 If there is a name you really want but it doesn't fit Orchard's
676 criteria, you can still go ahead. I thought <quote>gnubile</quote>
677 was one of the best I'd heard for a free software project ever and
678 I still talk about it long after I've stopped using the
679 program. However, if you can be flexible on the subject, listen to
680 Orchard's advice. It might help you.
684 <!-- Section2: licensing-->
686 <sect2 id="licensing">
687 <title>Licensing your Software</title>
690 On one (somewhat simplistic) level, the difference between a piece
691 of free software and a piece of propriety software is the
692 license. A license helps you as the developer by protecting your
693 legal rights to have your software distributed under your terms
694 and helps demonstrate to those who wish to help you or your
695 project that they are encouraged to join.
698 <sect3 id="chooselicense">
699 <title>Choosing a license</title>
702 Any discussion of licenses is also sure to generate at least a
703 small flame war as there are strong feelings that some free
704 software licenses are better than others. This discussion also
705 brings up the question of <quote>Open Source Software</quote> and
706 the debate over the terms <quote>Open Source Software</quote> and
707 <quote>Free Software</quote>. However, because I've written the
708 Free Software Project Management HOWTO and not the Open Source
709 Software Project Management HOWTO, my own allegiances in this
710 argument are in the open.
714 In attempting to reach a middle ground through diplomacy without
715 sacrificing my own philosophy, I will recommend picking any
716 license that conforms to the <ulink
717 url="http://www.debian.org/social_contract">Debian Free Software
718 Guidelines</ulink>. Originally compiled by the Debian project
719 under Bruce Perens, the <acronym>DFSG</acronym> forms the first
720 version of the <ulink
721 url="http://www.opensource.org/docs/definition_plain.html">Open
722 Source Definition.</ulink> Examples of free licenses given by the
723 <acronym>DFSG</acronym> are the <acronym>GPL</acronym>, the
724 <acronym>BSD</acronym>, and the Artistic License. As ESR mentions
725 in his his HOWTO<xref linkend="esrhowto">, don't write your own
726 license if at all possible. The three licenses I mention all have
727 long interpretive traditions. They are also definitely free
728 software (and can therefore be distributed as part of Debian and
729 in other places that permit the transfer of free software).
733 Conforming to the definition of free software offered by Richard
735 url="http://www.gnu.org/philosophy/free-sw.html"><quote>The Free
736 Software Definition</quote></ulink>, any of these licenses will
737 uphold, <quote>users' freedom to run, copy, distribute, study,
738 change and improve the software.</quote> There are plenty of
739 other licenses that also conform to the <acronym>DFSG</acronym>
740 but sticking with a more well-known license will offer the
741 advantage of immediate recognition and understanding.</para>
744 In attempting a more in-depth analysis, I agree with Karl Fogel's
745 description of licenses as falling into two groups: those that
746 are the <acronym>GPL</acronym> and those that are not the
747 <acronym>GPL</acronym>.
751 Personally, I license all my software under the
752 <acronym>GPL</acronym>. Created and protected by the Free
753 Software Foundation and the GNU Project, the
754 <acronym>GPL</acronym> is the license for the Linux kernel,
755 GNOME, Emacs, and the vast majority of GNU/Linux software. It's
756 the obvious choice but I also believe it is a good one. Any BSD
757 fanatic will urge you to remember that there is a viral aspect to
758 the <acronym>GPL</acronym> that prevents the mixture of
759 <acronym>GPL</acronym>'ed code with non-<acronym>GPL</acronym>'ed
760 code. To many people (myself included), this is a benefit, but to
761 some, it is a major drawback.
765 Many people write three or four sentences in a COPYING file and
766 assume that they have written a free software license--as my long
767 experience with the debian-legal mailing professes, this is very
768 often not the case. It may not protect you, it may not protect
769 your software, and it may make things very difficult for people
770 that want to use your software but who pay a lot of attention to
771 the subtle legal points of licenses. If you are passionate about
772 a home-brewed license, run it by either people at <ulink
773 url="http://www.opensource.org">OSI</ulink> or the <ulink
774 url="mailto:debian-devel@lists.debian.org">debian-legal mailing
775 list</ulink> first protect yourself from unanticipated
776 side-effects of your license.
780 The three major licenses can be found at the following locations:
786 <para><ulink url="http://www.gnu.org/copyleft/gpl.html">The GNU
787 General Public License</ulink></para>
790 <para><ulink url="http://www.debian.org/misc/bsd.license">The
791 BSD License</ulink></para>
795 url="http://language.perl.com/misc/Artistic.html">The Artistic
796 License</ulink></para>
802 <emphasis>In any case, please read through any license before
803 your release your software under it. As the primary developer,
804 you can't afford any license surprises.</emphasis>
808 <sect3 id="licensechoose">
809 <title>The mechanics of licensing</title>
812 The text of the <acronym>GPL</acronym> offers <ulink
813 url="http://www.gnu.org/copyleft/gpl.html#SEC4">a good
814 description of the mechanics of applying a license</ulink> to a
815 piece of software. My quick checklist for applying a license
823 <para>Make yourself or the FSF the copyright holder for the
824 work. In a few rare cases, you might want to make a sponsoring
825 organization (if it's big and powerful enough) the copyright
826 holder instead. Doing this is as simple as putting the name in
827 the blank when you modify the notice of copyright
828 below. Contrary to popular belief, you don't need to file with
829 any organization. The notice alone is enough to copyright your
834 <para>If at all possible, attach and distribute a full copy of
835 the license with the source and binary by including a separate
840 <para>At the top of each source file in your program, attach a
841 notice of copyright and include information on where the full
842 license can be found. The <acronym>GPL</acronym> recommends
843 that each file begin with:</para>
846 <emphasis>one line to give the program's name and an idea of what it does.</emphasis>
847 Copyright (C) yyyy name of author
849 This program is free software; you can redistribute it and/or
850 modify it under the terms of the GNU General Public License
851 as published by the Free Software Foundation; either version 2
852 of the License, or (at your option) any later version.
854 This program is distributed in the hope that it will be useful,
855 but WITHOUT ANY WARRANTY; without even the implied warranty of
856 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
857 GNU General Public License for more details.
859 You should have received a copy of the GNU General Public License
860 along with this program; if not, write to the Free Software
861 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
865 The <acronym>GPL</acronym> goes on to recommend attaching
866 information on methods for contacting you (the author) via
867 email or physical mail.
873 The <acronym>GPL</acronym> continues and suggests that if your
874 program runs in an interactive mode, you should write the
875 program to output a notice each time it enters interactive
876 mode that includes a message like this one that points to full
877 information about the programs license:
881 Gnomovision version 69, Copyright (C) year name of author
882 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
883 type `show w'. This is free software, and you are welcome
884 to redistribute it under certain conditions; type `show c'
890 <para>Finally, it might be helpful to include a
891 <quote>copyright disclaimer</quote> from an employer or a
892 school if you work as a programmer or if it seems like your
893 employer or school might be able to make an argument for
894 ownership of your code later on. These aren't often needed but
895 there are plenty of free software developers who have gotten
896 into trouble and wish they'd asked for one.</para>
903 <sect3 id="licensewarning">
904 <title>Final license warning</title>
907 Please, please, please, place your software under
908 <emphasis>some</emphasis> license. It may not seem important, and
909 to you it may not be, but licenses <emphasis>are</emphasis>
910 important. For a piece of software to be included in the Debian
911 GNU/Linux distribution, it must have a license that fits the
912 <ulink url="http://www.debian.org/social_contract">Debian Free
913 Software Guidelines</ulink>. If your software has no license, it
914 can not be distributed as a package in Debian until you
915 re-release it under a free license. Please save yourself and
916 others trouble by releasing the first version of your software
917 with a clear license.
924 <!-- Section2: chooseversioning-->
926 <sect2 id="chooseversioning">
927 <title>Choosing a Method of Version Numbering</title>
930 <emphasis>The most important thing about a system of version
931 numbering is that there is one.</emphasis> It may seem pedantic to
932 emphasize this point but you'd be surprised at the number of
933 scripts and small programs that pop up without any version number
938 <emphasis>The second most important thing about a system of
939 numbering is that the numbers always go up.</emphasis> Automatic
940 version tracking systems and people's sense of order in the
941 universe will fall apart if version numbers don't rise. It doesn't
942 <emphasis>really</emphasis> matter if 2.1 is a big jump and
943 2.0.005 is a small jump but it does matter that 2.1 is more recent
948 Follow these two simple rules and you will not go (too)
949 wrong. Beyond this, the most common technique seems to be the
950 <quote>major level,</quote> <quote>minor level,</quote>
951 <quote>patch level</quote> version numbering scheme. Whether you
952 are familiar with the name or not, you interact with it all the
953 time. The first number is the major number and it signifies major
954 changes or rewrites. The second number is the minor number and it
955 represents added or tweaked functionality on top of a largely
956 coherent structure. The third number is the patch number and it
957 usually will only refer to releases fixing bugs.
961 The widespread use of this scheme is why I know the nature and
962 relative degree in the differences between a 2.4.12 release of the
963 Linux kernel and a 2.4.11, 2.2.12, and 1.2.12 without knowing
964 anything about any of the releases.
968 You can bend or break these rules, and people do. But beware, if
969 you choose to, someone will get annoyed, assume you don't know,
970 and try and educate you, probably not nicely. I always follow this
971 method and I implore you to do so as well.
975 There are several version numbering systems that are well known,
976 useful, and that might be worth looking into before you release
982 <term>Linux kernel version numbering:</term>
984 <para>The Linux kernel uses a versioning system where any odd
985 minor version number refers to an development or testing release
986 and any even minor version number refers to a stable
987 version. Think about it for a second. Under this system, 2.1 and
988 2.3 kernels were and always will be development or testing
989 kernels and 2.0, 2.2. and 2.4 kernels are all production code
990 with a higher degree of stability and more testing.
994 Whether you plan on having a split development model (as
995 described in <xref linkend="branches">) or only one version
996 released at a time, my experience with several free software
997 projects and with the Debian project has taught me that use of
998 Linux's version numbering system is worth taking into
999 consideration. In Debian, <emphasis>all</emphasis> minor
1000 versions are stable distributions (2.0, 2.1, etc). However,
1001 many people assume that 2.1 is an unstable or development
1002 version and continue to use an older version until they get so
1003 frustrated with the lack of development progress that they
1004 complain and figure the system out. If you never release an odd
1005 minor version but only release even ones, nobody is hurt, and
1006 less people are confused. It's an idea worth taking into
1013 <term>Wine version numbering:</term>
1015 <para>Because of the unusual nature of wine's development where
1016 the not-emulator is constantly improving but not working toward
1017 any immediately achievable goal, wine is released every three
1018 weeks. Wine does this by labeling their releases in <quote>Year
1019 Month Day</quote> format where each release might be labeled
1020 <quote>wine-XXXXXXXX</quote> where the version from January 04,
1021 2000 would be <quote>wine-20000104</quote>. For certain
1022 projects, <quote>Year Month Day</quote> format can make a lot of
1029 <term>Mozilla milestones:</term>
1031 <para>When one considers Netscape 6 and vendor versions, the
1032 mozilla's project development structure is one of the most
1033 complex free software models available. The project's version
1034 numbering has reflected the unique situation in which it is
1039 Mozilla's version numbering structure has historically been
1040 made up of milestones. From the beginning of the mozilla
1041 project, the goals of the project in the order and degree to
1042 which they were to be achieved were charted out on a series of
1043 <ulink url="http://www.mozilla.org/roadmap.html">road
1044 maps</ulink>. Major points and achievements along these
1045 road-maps were marked as milestones. Therefore, although
1046 Mozilla was built and distributed nightly as <quote>nightly
1047 builds,</quote> on a day when the goals of a milestone on the
1048 road-map had been reached, that particular build was marked as
1049 a <quote>milestone release.</quote>
1053 While I haven't seen this method employed in any other projects
1054 to date, I like the idea and think that it might have value in
1055 any testing or development branch of a large application under
1064 <!-- Section2: documentation-->
1066 <sect2 id="documentation">
1067 <title>Documentation</title>
1070 A huge number of otherwise fantastic free software applications
1071 have withered and died because their author was the only person
1072 who knew how to use them fully. Even if your program is written
1073 primarily for a techno-savvy group of users, documentation is
1074 helpful and even necessary for the survival of your project. You
1075 will learn later in <xref linkend="releasing"> that you should
1076 always release something that is usable. <emphasis>A piece of
1077 software without documentation is not usable.</emphasis>
1081 There are lots of different people you should document for and
1082 there are lots of ways to document your project. <emphasis>The
1083 importance of documentation in source code to help facilitate
1084 development by a large community is vital</emphasis> but it falls
1085 outside the scope of this HOWTO. This being the case, this section
1086 deals with useful tactics for user-directed documentation.
1090 A combination of tradition and necessity has resulted in a
1091 semi-regular system of documentation in most free software
1092 projects that is worth following. Both users and developers expect
1093 to be able to get documentation in several ways and it's essential
1094 that you provide the information they are seeking in a form they
1095 can read if your project is ever going to get off the
1096 ground. People have come to expect:
1100 <title>Man pages</title>
1102 <para>Your users will want to be able to type <quote>man
1103 yourprojectname</quote> end up with a nicely formatted man page
1104 highlighting the basic use of your application. Make sure that
1105 before you release your program, you've planned for this.
1109 Man pages are not difficult to write. There is excellent
1110 documentation on the man page writing process available through
1111 the <quote>The Linux Man-Page-HOWTO</quote> which is available
1112 through the Linux Documentation project <acronym>(LDP)</acronym>
1113 and is written by Jens Schweikhardt. It is available <ulink
1114 url="http://www.schweikhardt.net/man_page_howto.html">from
1115 Schweikhardt's site</ulink>.
1119 It is also possible to write man pages using DocBook
1120 SGML. Because man pages are so simple and the DocBook method
1121 relatively new, I have not been able to follow this up but would
1122 love help from anyone who can give me more information on how
1123 exactly how this is done.
1128 <title>Command line accessible documentation</title>
1131 Most users will expect some basic amount of documentation to be
1132 easily available from the command line. For few programs should
1133 this type of documentation extend for more than one screen (24 or
1134 25 lines) but it should cover the basic usage, a brief (one or
1135 two sentence) description of the program, a list of the commands
1136 with explanations, as well as all the major options (also with
1137 explanations), plus a pointer to more in-depth documentation for
1138 those who need it. The command line documentation for Debian's
1139 apt-get serves as an excellent example and a useful model:
1143 apt 0.3.19 for i386 compiled on May 12 2000 21:17:27
1144 Usage: apt-get [options] command
1145 apt-get [options] install pkg1 [pkg2 ...]
1147 apt-get is a simple command line interface for downloading and
1148 installing packages. The most frequently used commands are update
1152 update - Retrieve new lists of packages
1153 upgrade - Perform an upgrade
1154 install - Install new packages (pkg is libc6 not libc6.deb)
1155 remove - Remove packages
1156 source - Download source archives
1157 dist-upgrade - Distribution upgrade, see apt-get(8)
1158 dselect-upgrade - Follow dselect selections
1159 clean - Erase downloaded archive files
1160 autoclean - Erase old downloaded archive files
1161 check - Verify that there are no broken dependencies
1165 -q Loggable output - no progress indicator
1166 -qq No output except for errors
1167 -d Download only - do NOT install or unpack archives
1168 -s No-act. Perform ordering simulation
1169 -y Assume Yes to all queries and do not prompt
1170 -f Attempt to continue if the integrity check fails
1171 -m Attempt to continue if archives are unlocatable
1172 -u Show a list of upgraded packages as well
1173 -b Build the source package after fetching it
1174 -c=? Read this configuration file
1175 -o=? Set an arbitary configuration option, eg -o dir::cache=/tmp
1176 See the apt-get(8), sources.list(5) and apt.conf(5) manual
1177 pages for more information and options.
1181 It has become a GNU convention to make this type of information
1182 accessible with the <quote>-h</quote> and the
1183 <quote>--help</quote> options. Most GNU/Linux users will expect
1184 to be able to retrieve basic documentation these ways so if you
1185 choose to use different methods, be prepared for the flames and
1186 fallout that may result.
1191 <title>Files users will expect</title>
1193 In addition to man pages and command-line help, there are certain
1194 files where people will look for documentation, especially in any
1195 package containing source code. In a source distribution, most of
1196 these files can be stored in the root directory of the source
1197 distribution or in a subdirectory of the root called
1198 <quote>doc</quote> or <quote>Documentation.</quote> Common files
1199 in these places include:
1205 <term>README or Readme</term>
1208 <para>A document containing all the basic installation,
1209 compilation, and even basic use instructions that make up the
1210 bare minimum information needed to get the program up and
1211 running. A README is not your chance to be verbose but should
1212 be concise and effective. An ideal README is at least 30 lines
1213 long and more no more than 250.</para>
1218 <term>INSTALL or Install</term>
1221 <para>The INSTALL file should be much shorter than the README
1222 file and should quickly and concisely describe how to build
1223 and install the program. Usually an INSTALL file simply
1224 instructs the user to run <quote>./configure; make; make
1225 install</quote> and touches on any unusual options or actions
1226 that may be necessary. For most relatively standard install
1227 procedures and for most programs, INSTALL files are as short
1228 as possible and are rarely over 100 lines.</para>
1233 <term>CHANGELOG, Changelog, ChangeLog, or changelog</term>
1236 <para>A CHANGELOG is a simple file that every well-managed
1237 free software project should include. A CHANGELOG is simple
1238 the file that, as its name implies, logs or documents the
1239 changes you make to your program. The most simple way to
1240 maintain a CHANGELOG is to simply keep a file with the source
1241 code for your program and add a section to the top of the
1242 CHANGELOG with each release describing what has been changed,
1243 fixed, or added to the program. It's a good idea to post the
1244 CHANGELOG onto the website as well because it can help people
1245 decide whether they want or need to upgrade to a newer version
1246 or wait for a more significant improvement.</para>
1254 <para>A NEWS file and a ChangeLog are similar. Unlike a
1255 CHANGELOG, a NEWS file is not typically updated with new
1256 versions. Whenever new features are added, the developer
1257 responsible will make a note in the NEWS file. NEWS files
1258 should not have to be changed before a release (they should be
1259 kept up to date all along) but it's usually a good idea to
1260 check first anyway because often developers just forget to
1261 keep them as current as they should.</para>
1266 <term><acronym>FAQ</acronym></term>
1269 <para>For those of you that don't already know,
1270 <acronym>FAQ</acronym> stands for Frequently Asked Questions
1271 and a FAQ is a collection of exactly that. FAQs are not
1272 difficult to make. Simply make a policy that if you are asked
1273 a question or see a question on a mailing list two or more
1274 times, add the question (and its answer) to your FAQ. FAQs are
1275 more optional than the files listed above but they can save
1276 your time, increase usability, and decrease headaches on all
1286 <title>Website</title>
1288 It's only indirectly an issue of documentation but a good website
1289 is quickly becoming an essential part of any free software
1290 project. Your website should provide access to your documentation
1291 (in <acronym>HTML</acronym> if possible). It should also include
1292 a section for news and events around your program and a section
1293 that details the process of getting involved with development or
1294 testing and make an open invitation. It should also supply links
1295 to any mailing lists, similar websites, and provide a direct link
1296 to all the available ways of downloading your software.
1301 <title>Other documentation hints</title>
1306 All your documentation should be in plaintext, or, in cases
1307 where it is on your website primarily, in HTML. Everyone can
1308 cat a file, everyone has a pager, (almost) everyone can render
1309 HTML. <emphasis>You are welcome to distribute information in
1310 PDF, PostScript, RTF, or any number of other widely used
1311 formats but this information must also be available in
1312 plaintext or HTML or people will be very angry at
1313 you.</emphasis> In my opinion, info falls into this category
1314 as well. There is plenty of great GNU documentation that
1315 people simply don't read because it only in info. And this
1316 <emphasis>does</emphasis> make people angry. It's not a
1317 question of superior formats; it is a question of
1318 accessability and the status quo plays a huge role in this
1325 It doesn't hurt to distribute any documentation for your
1326 program from your website (FAQs etc) with your program. Don't
1327 hesitate to throw any of this in the program's tarball. If
1328 people don't need it, they will delete it. I can repeat it over
1329 and over: <emphasis>Too much documentation is not a
1335 <para>Unless your software is particular to a non-English
1336 language (a Japanese language editor for example), please
1337 distribute it with English language documentation. If you don't
1338 speak English or not not confident in your skills, ask a friend
1339 for help. Like it or not, fair or unfair, <emphasis>English is
1340 the language of free software</emphasis>. However, this does not
1341 mean you should limit your documentation to only English. If you
1342 speak another language, distribute translations of documentation
1343 with your software if you have the time and energy to do
1344 so. They will invariably be useful to someone.</para>
1349 Finally, <emphasis>please spell-check your
1350 documentation.</emphasis> Misspellings in documentation are
1351 bugs. I'm very guilty of committing this error and it's
1352 extremely easy to do. If English is not your first language,
1353 have a native speaker look over or edit your documentation or
1354 web pages. Poor spelling or grammar goes a long way to making
1355 your code look unprofessional. In code comments, this type of
1356 thing is less important but in man pages and web pages these
1357 mistakes are not acceptable.
1367 <!-- Section2: presentation -->
1369 <sect2 id="presentation">
1370 <title>Other Presentation Issues</title>
1372 Many of the remaining issues surrounding the creation of a new
1373 free software program fall under what most people describe as
1374 common sense issues. Its often said that software engineering is
1375 90 percent common sense combined with 10 percent specialized
1376 knowledge. Still, they are worth noting briefly in hopes that they
1377 may remind a developer of something they may have forgotten.
1381 <title>Package File Names</title>
1383 I agree with ESR when he says that: <quote> It's helpful to
1384 everybody if your archive files all have GNU-like names --
1385 all-lower-case alphanumeric stem prefix, followed by a dash,
1386 followed by a version number, extension, and other
1387 suffixes.</quote> There is more info (including lots of examples
1388 of what <emphasis>not</emphasis> to do in his <citetitle>Software
1389 Release Practices HOWTO</citetitle> which is included in this
1390 HOWTO's bibliography and can be found through the LDP.
1395 <title>Package formats</title>
1397 Package formats may differ depending on the system you are
1398 developing for. For windows based software, Zip archives (.zip)
1399 usually serve as the package format of choice. If you are
1400 developing for GNU/Linux, *BSD, or any UN*X, make sure that your
1401 source code is always available in tar'ed and gzip'ed format
1402 (.tar.gz). UNIX compress (.Z) has gone out of style and
1403 usefulness and faster computers have brought bzip2 (.bz2) into
1404 the spot-light as a more effective compression medium. I now make
1405 all my releases available in both gzip'ed and bzip2'ed tarballs.
1409 Binary packages should always be distribution specific. If you
1410 can build binary packages against a current version of a major
1411 distribution, you will only make your users happy. Try to foster
1412 relationships with users or developers of large distributions to
1413 develop a system for the consistent creation of binary
1414 packages. It's often a good idea to provide RedHat
1415 <acronym>RPM</acronym>'s (.rpm), Debian deb's (.deb) and source
1416 <acronym>RPM</acronym>'s <acronym>SRPM</acronym>'s if
1417 possible. Remember: <emphasis>While these binaries packages are
1418 nice, getting the source packaged and released should always be
1419 your priority. Your users or fellow developers can and will do
1420 the the binary packages for you.</emphasis>
1425 <title>Version control systems</title>
1428 A version control system can make a lot of these problems of
1429 packaging (and a lot of other problems mentioned in this HOWTO)
1430 less problematic. If you are using *NIX, CVS is your best bet. I
1431 recommend Karl Fogel's book on the subject (and the <ulink
1432 url="http://cvsbook.red-bean.com/">posted HTML version</ulink>)
1437 CVS or not, you should probably invest some time into learning
1438 about a version control system because it provides an automated
1439 way of solving many of the problems described by this HOWTO. I
1440 am not aware of any free version control systems for Windows or
1441 Mac OS but I know that CVS clients exist for both
1442 platforms. Websites like <ulink
1443 url="http://sourceforge.net">SourceForge</ulink> do a great job
1444 as well with a nice, easy-to-use web interface to CVS.
1448 I'd love to devote more space in this HOWTO to CVS because I love
1449 it (I even use CVS to keep versions straight on this HOWTO!) but
1450 I think it falls outside the scope of this document and already
1451 has its own HOWTOs. Most notably is the <citetitle>CVS Best
1452 Practices HOWTO</citetitle><xref linkend="cvsbestpractices">
1453 which I've included in the attached bibliography.
1459 <title>Useful tidbits and presentation hints</title>
1462 Other useful hints include:
1470 <emphasis>Make sure that your program can always be found in a
1471 single location.</emphasis> Often this means that you have a
1472 single directory accessible via <acronym>FTP</acronym> or the
1473 web where the newest version can be quickly recognized. One
1474 effective technique is a provide a symlink called
1475 <quote>yourprojectname-latest</quote> that is always pointing
1476 to the most recent released or development version of your
1477 free software application. Keep in mind that this location
1478 will receive many requests for downloads around releases so
1479 make sure that the server you choose has adequate bandwidth.
1485 <emphasis>Make sure that there is a consistent email address
1486 for bug reports.</emphasis> It's usually a good idea to make
1487 this something that is NOT your primary email address like
1488 yourprojectname@host or yourprojectname-bugs@host. This way,
1489 if you ever decide to hand over maintainership or if your
1490 email address changes, you simply need to change where this
1491 email address forwards. It also will allow for more than one
1492 person to deal with the influx of mail that is created if your
1493 project becomes as huge as you hope it will.
1503 <!-- Section1: starting: END -->
1505 <!-- Section1: developers -->
1507 <sect1 id="developers">
1508 <title>Maintaining a Project: Interacting with Developers</title>
1510 <primary>fswd!developers</primary>
1514 Once you have gotten your project started, you have overcome the
1515 most difficult hurdles in the development process of your
1516 program. Laying a firm foundation is essential, but the development
1517 process itself is equally important and provides just as many
1518 opportunities for failure. In the next two sections, I will
1519 describe running a project by discussing how to maintain a
1520 development effort through interactions with developers and with
1525 In releasing your program, your program becomes free software. This
1526 transition is more than just a larger user base. By releasing your
1527 program as free software, <emphasis>your</emphasis> software
1528 becomes the <emphasis>free software community's</emphasis>
1529 software. The direction of your software's development will be
1530 reshaped, redirected, and fully determined by your users and, to a
1531 larger extent, by other developers in the community.
1535 The major difference between free software development and
1536 propriety software development is the developer base. As the leader
1537 of a free software project, you need to attract and keep developers
1538 in a way that leaders of proprietary software projects simply don't
1539 have to worry about. <emphasis>As the person leading development of
1540 a free software project, you must harness the work of fellow
1541 developers by making responsible decisions and by responsibly
1542 choosing not to make decisions. You have to direct developers
1543 without being overbearing or bossy. You need to strive to earn
1544 respect and never forget to give it out.</emphasis>
1547 <!-- Section2: delegation -->
1549 <sect2 id="delegation">
1550 <title>Delegating Work</title>
1553 By now, you've hypothetically followed me through the early
1554 programming of a piece of software, the creation of a website and
1555 system of documentation, and we've gone ahead and (as will be
1556 discussed in <xref linkend="releasing">) released it to the rest
1557 of the world. Times passes, and if things go well, people become
1558 interested and want to help. The patches begin flowing in.
1562 <emphasis>Like the parent of any child who grows up, it's now time
1563 to wince, smile and do most difficult thing in any parents
1564 life: It's time to let go.</emphasis>
1568 Delegation is the political way of describing this process of
1569 <quote>letting go.</quote> It is the process of handing some of
1570 the responsibility and power over your project to other
1571 responsible and involved developers. It is difficult for anyone
1572 who has invested a large deal of time and energy into a project
1573 but it essential for the growth of any free software project. One
1574 person can only do so much. A free software project is nothing
1575 without the involvement of <emphasis>a group</emphasis> of
1576 developers. A group of developers can only be maintained through
1577 respectful and responsible leadership and delegation.
1581 As your project progresses, you will notice people who are putting
1582 significant amounts of time and effort into your project. These
1583 will be the people submitting the most patches, posting most on
1584 the mailing lists, and engaging in long email discussions. It is
1585 your responsibility to contact these people and to try and shift
1586 some of the power and responsibility of your position as the
1587 project's maintainer onto them (if they want it). There are
1588 several easy ways you can do this:
1592 In a bit of a disclaimer, delegation need not mean rule by
1593 committee. In many cases it does and this has been proven to
1594 work. In other cases this has created problems. <ulink
1595 url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
1596 Projects the Open Source Way</ulink> argues that <quote>OSS
1597 projects do best when one person is the clear leader of a team and
1598 makes the big decisions (design changes, release dates, and so
1599 on).</quote> I think this often true but would urge developers to
1600 consider the ideas that the project leader need not be the
1601 project's founder and that these important powers need not all rest
1602 with one person but that a release manager may be different than a
1603 lead developer. These situations are tricky politically so
1604 be careful and make sure it's necessary before you go around
1609 <title>How to delegate</title>
1612 You may find that other developers seem even more experienced or
1613 knowledgeable than you. Your job as a maintainer does not mean
1614 you have to be the best or the brightest. It means you
1615 are responsible for showing good judgment and for
1616 recognizing which solutions are maintainable and which are not.
1619 Like anything, its easier to watch others delegate than to do it
1620 yourself. In a sentence: <emphasis>Keep an eye out for other
1621 qualified developers who show an interest and sustained
1622 involvement with your project and try and shift responsibility
1623 toward them.</emphasis> The following ideas might be good places
1624 to start or good sources of inspiration:
1628 <title>Allow a larger group of people to have write access to your CVS
1629 repository and make real efforts toward rule by a
1633 <ulink url="http://httpd.apache.org/">Apache</ulink> is an
1634 example of a project that is run by small group of developers
1635 who vote on major technical issues and the admission of new
1636 members and all have write access to the main source
1637 repository. Their process is detailed <ulink
1638 url="http://httpd.apache.org/ABOUT_APACHE.html">online.</ulink>
1642 The <ulink url="http://www.debian.org/"> Debian Project</ulink>
1643 is an extreme example of rule by committee. At current count,
1644 more than 700 developers have full responsibility for
1645 aspects of the project. All these developers can upload into
1646 the main FTP server, and vote on major issues. Direction for
1647 the project is determined by the project's <ulink
1648 url="http://www.debian.org/social_contract">social
1649 contract</ulink> and a <ulink
1650 url="http://www.debian.org/devel/constitution">constitution</ulink>. To
1651 facilitate this system, there are special teams (i.e. the
1652 install team, the Japanese language team) as well as a technical
1653 committee and a project leader. The leader's main responsibility
1654 is to, <quote>appoint delegates or delegate decisions to the
1655 Technical Committee.</quote>
1659 While both of these projects operate on a scale that your
1660 project will not (at least initially), their example is
1661 helpful. Debian's idea of a project leader who can do
1662 <emphasis>nothing</emphasis> but delegate serves as a
1663 caricature of how a project can involve and empower a huge
1664 number of developers and grow to a huge size.
1669 <sect4 id="releasemanager">
1670 <title>Publicly appoint someone as the release manager for a
1671 specific release</title>
1674 A release manager is usually responsible for coordinating
1675 testing, enforcing a code freeze, being responsible for
1676 stability and quality control, packaging up the software, and
1677 placing it in the appropriate places to be downloaded.
1681 This use of the release manager is a good way to give yourself a
1682 break and to shift the responsibility for accepting and
1683 rejecting patches onto someone else. It is a good way of very
1684 clearly defining a chunk of work on the project as belonging to
1685 a certain person and its a great way of giving yourself room to
1690 <sect4 id="delegatebranch">
1691 <title>Delegate control of an entire branch</title>
1693 If your project chooses to have branches (as described in <xref
1694 linkend="branches">), it might be a good idea to appoint someone
1695 else to be the the head of a branch. If you like focusing your
1696 energy on development releases and the implementation of new
1697 features, hand total control over the stable releases to a
1698 well-suited developer.
1702 The author of Linux, Linus Torvalds, came out and crowned Alan
1703 Cox as <quote>the man for stable kernels.</quote> All patches
1704 for stable kernels go to Alan and, if Linus were to be taken
1705 away from work on Linux for any reason, Alan Cox would be more
1706 than suited to fill his role as the acknowledged heir to the
1707 Linux maintainership.
1713 <!-- Section2: patching -->
1715 <sect2 id="patching">
1716 <title>Accepting and Rejecting Patches</title>
1718 This HOWTO has already touched on the fact that as the maintainer
1719 of a free software project, one of your primary and most important
1720 responsibilities will be accepting and rejecting patches submitted
1721 to you by other developers.
1725 <title>Encouraging Good Patching</title>
1727 <para>As the person managing or maintaining the project, you
1728 aren't the person who is going to be making a lot of
1729 patches. However, it's worth knowing about ESR's section on
1730 <citetitle>Good Patching Practice</citetitle> in the
1731 <citetitle>Software Release Practices HOWTO</citetitle><xref
1732 linkend="esrhowto">. I don't agree with ESR's claim that most ugly
1733 or undocumented patches are probably worth throwing out at first
1734 sight--this just hasn't been my experience, especially when
1735 dealing with bug fixes that often don't come in the form of
1736 patches at all. Of course, this doesn't mean that I
1737 <emphasis>like</emphasis> getting poorly done patches. If you get
1738 ugly -e patches, if you get totally undocumented patches, and
1739 especially if they are anything more than trivial bug-fixes, it
1740 might be worth judging the patch by some of the criteria in ESR's
1741 HOWTO and then throwing people the link to the document so they
1742 can do it the <quote>right way.</quote>
1748 <title>Technical judgment</title>
1751 In <emphasis>Open Source Development with CVS</emphasis>, Karl
1752 Fogel makes a convincing argument that the most important things
1753 to keep in mind when rejecting or accepting patches are:
1760 <para>A firm knowledge of the scope of your program (that's the
1761 <quote>idea</quote> I talked about in <xref linkend="chooseproject">);</para>
1765 <para>The ability to recognize, facilitate, and direct
1766 <quote>evolution</quote> of your program so that the program
1767 can grow and change and incorporate functionality that was
1768 originally unforeseen;</para>
1772 <para>The necessity to avoid digressions that might expand the
1773 scope of the program too much and result and push the project
1774 toward an early death under its own weight and
1775 unwieldiness.</para>
1782 These are the criteria that you as a project maintainer should
1783 take into account each time you receive a patch.
1787 Fogel elaborates on this and states the <quote>the
1788 questions to ask yourself when considering whether to implement
1789 (or approve) a change are:</quote>
1796 <para>Will it benefit a significant percentage of the program's
1797 user community?</para>
1801 <para>Does it fit within the program's domain or within a
1802 natural, intuitive extension of that domain?</para>
1809 The answers to these questions are never straightforward and its
1810 very possible (and even likely) that the person who submitted the
1811 patch may feel differently about the answer to these questions
1812 than you do. However, if you feel that that the answer to either
1813 of those questions is <quote>no,</quote> it is your responsibility
1814 to reject the change. If you fail to do this, the project will
1815 become unwieldy and unmaintainable and many ultimately fail.
1820 <title>Rejecting patches</title>
1823 Rejecting patches is probably the most difficult and sensitive
1824 job that the maintainer of any free software project has to
1825 face. But sometimes it has to be done. I mentioned earlier (in
1826 <xref linkend="developers"> and in <xref linkend="delegation">)
1827 that you need to try and balance your responsibility and power to
1828 make what you think are the best technical decisions with the
1829 fact that you will lose support from other developers if you seem
1830 like you are on a power trip or being overly bossy or possessive
1831 of the community's project. I recommend that you keep these three
1832 major concepts in mind when rejecting patches (or other changes):
1836 <title>Bring it to the community</title>
1838 One of the best ways of justifying a decision to reject a patch
1839 and working to not seem like you keep an iron grip on your
1840 project is by not making the decision alone at all. It might
1841 make sense to turn over larger proposed changes or more
1842 difficult decisions to a development mailing list where they can
1843 be discussed and debated. There will be some patches (bug fixes,
1844 etc.) which will definitely be accepted and some that you feel
1845 are so off base that they do not even merit further
1846 discussion. It is those that fall into the gray area between
1847 these two groups that might merit a quick forward to a mailing
1852 I recommend this process wholeheartedly. As the project
1853 maintainer you are worried about making the best decision for
1854 the project, for the project's users and developers, and for
1855 yourself as a responsible project leader. Turning things over to
1856 an email list will demonstrate your own responsibility and
1857 responsive leadership as it tests and serves the interests of
1858 your software's community.
1863 <title>Technical issues are not always good justification</title>
1865 Especially toward the beginning of your project's life, you
1866 will find that many changes are difficult to implement,
1867 introduce new bugs, or have other technical problems. Try to see
1868 past these. Especially with added functionality, good ideas do
1869 not always come from good programmers. Technical merit is a
1870 valid reason to postpone an application of a patch but it is not
1871 always a good reason to reject a change outright. Even small
1872 changes are worth the effort of working with the developer
1873 submitting the patch to iron out bugs and incorporate the change
1874 if you think it seems like a good addition to your project. The
1875 effort on your part will work to make your project a community
1876 project and it will pull a new or less experienced developer
1877 into your project and even teach them something that might help
1878 them in making their next patch.
1883 <title>Common courtesy</title>
1885 It should go without saying but, <emphasis>above all and in all
1886 cases, just be nice.</emphasis> If someone has an idea and cares
1887 about it enough to write some code and submit a patch, they
1888 care, they are motivated, and they are already involved. Your
1889 goal as the maintainer is make sure they submit again. They may
1890 have thrown you a dud this time but next time may be the idea or
1891 feature that revolutionizes your project.
1895 It is your responsibility to first justify your choice to not
1896 incorporate their change clearly and concisely. Then thank
1897 them. Let them know that you a appreciate their help and feel
1898 horrible that you can't incorporate their change. Let them know
1899 that you look forward to their staying involved and you hope
1900 that the next patch or idea meshes better with your project
1901 because you appreciate their work and want to see it in your
1902 application. If you have ever had a patch rejected after putting
1903 a large deal of time, thought, and energy into it, you remember
1904 how it feels and it feels bad. Keep this in mind when you have
1905 to let someone down. It's never easy but you need to do
1906 everything you can to make it as not-unpleasant as possible.
1912 <!-- Section2: branches -->
1914 <sect2 id="branches">
1915 <title>Stable and Development Branches</title>
1918 The idea of stable and development branches has already been
1919 described briefly in <xref linkend="chooseversioning"> and in
1920 <xref linkend="delegatebranch">. These allusions attest to some of
1921 the ways that multiple branches can affect your software. Branches
1922 can let you avoid (to some extent) some of the problems around
1923 rejecting patches (as described in <xref linkend="patching">) by
1924 allowing you to temporarily compromise the stability of your
1925 project without affecting those users who need that stability.
1929 The most common way of branching your project is to have one
1930 branch that is stable and one that is for development. This is the
1931 model followed by the Linux kernel that is described in <xref
1932 linkend="chooseversioning">. In this model, there is
1933 <emphasis>always</emphasis> one branch that is stable and always
1934 one that is in development. Before any new release, the
1935 development branch goes into a <quote>feature freeze</quote> as
1936 described in <xref linkend="freezing"> where major changes and
1937 added features are rejected or put on hold under the development
1938 kernel is released as the new stable branch and major development
1939 resumes on the development branch. Bug fixes and small changes
1940 that are unlikely to have any large negative repercussions are
1941 incorporated into the stable branch as well as the development
1946 Linux's model provides an extreme example. On many projects, there is no
1947 need to have two versions constantly available. It may make sense to
1948 have two versions only near a release. The Debian project has
1949 historically made both a stable and an unstable distribution
1950 available but has expanded to this to include: stable, unstable,
1951 testing, experimental, and (around release time) a frozen
1952 distribution that only incorporates bug fixes during the
1953 transition from unstable to stable. There are few projects whose
1954 size would necessitate a system like Debian's but this use of
1955 branches helps demonstrate how they can be used to balance
1956 consistent and effective development with the need to make regular
1957 and usable releases.
1961 In trying to set up a development tree for yourself, there are
1962 several things that might be useful to keep in mind:
1969 <term>Minimize the number of branches</term>
1971 <para>Debian may be able to make good use of four or five
1972 branches but it contains gigabytes of software in over 5000
1973 packages compiled for 5-6 different architectures. For you,
1974 two is probably a good ceiling. Too many branches will confuse
1975 your users (I can't count how many times I had to describe
1976 Debian's system when it only had 2 and sometimes 3 branches!),
1977 potential developers and even yourself. Branches can help but
1978 they come at a cost so use them very sparingly.</para>
1983 <term>Make sure that all your different branches are explained</term>
1985 <para>As I mentioned in the preceding paragraph, different
1986 branches <emphasis>will</emphasis> confuse your users. Do
1987 everything you can to avoid this by clearly explaining the
1988 different branches in a prominent page on your website and in a
1989 README file in the <acronym>FTP</acronym> or
1990 web directory.</para>
1993 I might also recommend against a mistake that I think Debian
1994 has made. The terms <quote>unstable,</quote>
1995 <quote>testing,</quote> and <quote>experimental</quote> are
1996 vague and difficult to rank in order of stability (or
1997 instability as the case may be). Try explaining to someone
1998 that <quote>stable</quote> actually means <quote>ultra
1999 stable</quote> and that <quote>unstable</quote> doesn't
2000 actually include any unstable software but is really stable
2001 software that is untested as a distribution.
2005 If you are going to use branches, especially early on, keep in
2006 mind that people are conditioned to understand the terms
2007 <quote>stable</quote> and <quote>development</quote> and you
2008 probably can't go wrong with this simple and common division of
2015 <term>Make sure all your branches are always available</term>
2017 <para>Like a lot of this document, this should probably should
2018 go without saying but experience has taught me that it's not
2019 always obvious to people. It's a good idea to physically split
2020 up different branches into different directories or directory
2021 trees on your <acronym>FTP</acronym> or web site. Linux
2022 accomplishes this by having kernels in a v2.2 and a v2.3
2023 subdirectory where it is immediately obvious (after you know
2024 their version numbering scheme) which directory is for the most
2025 recent stable and the current development releases. Debian
2026 accomplishes this by naming all their distribution with names
2027 (i.e. woody, potato, etc.) and then changing symlinks named
2028 <quote>stable,</quote> <quote>unstable</quote> and
2029 <quote>frozen</quote> to point to which ever distribution (by
2030 name) is in whatever stage. Both methods work and there are
2031 others. In any case, it is important that different branches
2032 are always available, are accessible from consistent locations,
2033 and that different branches are clearly distinguished from each
2034 other so your users know exactly what they want and where to
2044 <!-- Section2: otherdev -->
2046 <sect2 id="otherdev">
2047 <title>Other Project Management issues</title>
2049 There are more issues surrounding interaction with developers in a
2050 free software project that I can not touch on in great detail in a
2051 HOWTO of this size and scope. Please don't hesitate to contact me if you see
2052 any major omissions.
2056 Other smaller issues that are worth mentioning are:
2059 <sect3 id="freezing">
2060 <title>Freezing</title>
2062 For those projects that choose to adopt a split development model
2063 (<xref linkend="branches">), freezing is a concept that is worth
2064 becoming familiar with.
2068 Freezes come in two major forms. A <quote>feature freeze</quote>
2069 is a period when no significant functionality is added to a
2070 program. It is a period where established functionality (even
2071 skeletons of barely working functionality) can be improved and
2072 perfected. It is a period where bugs are fixed. This type of
2073 freeze is usually applied some period (a month or two) before a
2074 release. It is easy to push a release back as you wait for
2075 <quote>one more feature</quote> and a freeze helps to avoid this
2076 situation by drawing the much needed line in the sand. It gives
2077 developers room they need to get a program ready for release.
2081 The second type of freeze is a <quote>code freeze</quote> which
2082 is much more like a released piece of software. Once a piece of
2083 software has entered a <quote>code freeze,</quote> all changes to
2084 the code are discouraged and only changes that fix known bugs
2085 are permitted. This type of freeze usually follows a
2086 <quote>feature freeze</quote> and directly precedes a
2087 release. Most released software is in what could be interpreted
2088 as a sort of high level <quote>code freeze.</quote>
2092 Even if you never choose to appoint a release manager (<xref
2093 linkend="releasemanager">), you will have an easier time
2094 justifying the rejection or postponement of patches (<xref
2095 linkend="patching">) before a release with a publicly stated
2102 <title>Forks</title>
2104 I wasn't sure about how I would deal with forking in this
2105 document (or if I would deal with forking at all). A fork is when
2106 a group of developers takes code from a free software project and
2107 actually starts a brand new free software project with it. The
2108 most famous example of a fork was between Emacs and XEmacs. Both
2109 emacsen are based on an identical code-base but for technical,
2110 political, and philosophical reasons, development was split into
2111 two projects which now compete with each other.
2115 The short version of the fork section is, <emphasis>don't do
2116 them.</emphasis> Forks force developers to choose one project to
2117 work with, cause nasty political divisions, and redundancy of
2118 work. Luckily, usually the threat of the fork is enough to scare
2119 the maintainer or maintainers of a project into changing the way
2120 they run their project.
2124 In his chapter on <quote>The Open Source Process,</quote> Karl
2125 Fogel describes how to do a fork if you absolutely must. If you
2126 have determined that is absolutely necessary and that the
2127 differences between you and the people threatening to fork are
2128 absolutely unresolvable, I recommend Fogel's book as a good place
2134 <!-- Section1: users -->
2137 <title>Maintaining a Project: Interacting with Users</title>
2139 <primary>fswd!users</primary>
2143 If you've worked your way up to here, congratulations, you are
2144 nearing the end of this document. This final section describes some
2145 of the situations in which you, in your capacity as project
2146 maintainer, will be interacting with users. It gives some
2147 suggestions on how these situations might be handled effectively.
2151 Interacting with users is difficult. In our discussion of
2152 interaction with developers, the underlying assumption is that in a
2153 free software project, a project maintainer must constantly strive to
2154 attract and keep developers who can easily leave at any time.
2158 Users in the free software community are different than developers
2159 and are also different than users in the world of proprietary
2160 software and they should be treated differently than either
2161 group. Some ways in which the groups differ significantly follow:
2168 <para>The lines between users and developers are blurred in ways
2169 that is totally foreign to any proprietary development
2170 model. Your users are often your developers and vice
2175 <para>In the free software world, you are often your users' only
2176 choice. Because there is such an emphasis on not replicating the
2177 work of others in the free software community and because the
2178 element of competition present in the propriety software model is
2179 absent (or at least in an extremely different form) in the free
2180 software development model, you will probably be the only project
2181 that does what you do (or at least the only one that does what
2182 you do in the way that you do it). This means your responsiveness
2183 to your users is even more important than in the proprietary
2184 software world.</para>
2188 <para>In an almost paradoxical situation, free software projects
2189 have less immediate or dire consequences for ignoring their users
2190 altogether. It is also often easier to do. Because you don't
2191 usually need to compete with another product, chances are good
2192 that you will not be scrambling to gain the features of your
2193 competitor's newest program. This means that your development
2194 process will have to be directed either internally, by a
2195 commitment to your users, or through both.</para>
2201 Trying to tackle this unique situation can only be done
2202 indirectly. Developers and maintainers need to listen to users and
2203 to try and be as responsive as possible. A solid knowledge of the
2204 situation recounted above is any free software developer's best tool
2205 for shifting his development or leadership style to fit the unique
2206 process of free software project management. This chapters will try and
2207 introduce some of the more difficult or important points in any
2208 projects interactions with users and give some hints on how to
2212 <!-- Section2: testing -->
2214 <sect2 id="testing">
2215 <title>Testing and Testers</title>
2218 In addition to your users being your developers, they are also
2219 (and perhaps more commonly) your testers. Before I get flamed, I
2220 should rephrase my sentence: <emphasis>some of your
2221 users</emphasis> (those who explicitly volunteer) are your
2226 It is important that this distinction be made early on because not
2227 all of your users want to be testers. Many users want to use
2228 stable software and don't care if they don't have the newest,
2229 greatest software with the latest, greatest features. These users
2230 except a stable, tested piece of software without major or obvious
2231 bugs and will be angry if they find themselves testing. This is
2232 yet another way in which a split development model (as mentioned
2233 in <xref linkend="branches">) might come in handy.
2238 url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
2239 Projects the Open Source Way</ulink></quote> describes what a
2240 good test should look for:
2245 <term>Boundary conditions</term>
2248 <para>Maximum buffer lengths, data conversions, upper/lower
2249 boundary limits, and so on.</para>
2254 <term>Inappropriate behavior</term>
2257 <para>Its a good idea to find out what a program will do if a
2258 user hands it a value it isn't expecting, hits the wrong button,
2259 etc. Ask yourself a bunch of <quote>what if</quote> questions
2260 and think of anything that <emphasis>might</emphasis> fail or
2261 <emphasis>might</emphasis> go wrong and find out what your
2262 program would do in those cases.</para>
2267 <term>Graceful failure</term>
2270 <para>The answer to a number of the <quote>what if</quote>
2271 questions above is probably <quote>failure</quote> which is
2272 often the only answer. Now make sure that it happens
2273 nicely. Make sure that when it crashes, there is some indication
2274 of why it crashed or failed so that the user or developer
2275 understands whats going on.</para>
2281 <term>Standards conformance</term>
2284 <para>If possible, make sure your programs conforms to
2285 standards. If it's interactive, don't be too creative with
2286 interfaces. If it is non-interactive, make sure it communicates
2287 over appropriate and established channels with other programs
2288 and with the rest of the system.</para>
2295 <title>Automated testing</title>
2297 For many programs, many common mistakes can be caught by
2298 automated means. Automated tests tend to be pretty good at
2299 catching errors that you've run into several times before or
2300 the things you just forget. They are not very good at finding
2301 errors, even major ones, that are totally unforeseen.
2305 CVS comes with a Bourne shell script called sanity.sh that is
2306 worth looking at. Debian uses a program called lintian that
2307 checks Debian packages for all of the most common errors. While
2308 use of these scripts may not be helpful, there is a host of other
2309 sanity checking software on the net that may be applicable (feel
2310 free to email me any recommendations). None of these will create
2311 a bug-free release but they will avoid at least some major
2312 oversights. Finally, if your programs become a long term
2313 endeavor, you will find that there are certain errors that you
2314 tend to make over and over. Start a collection of scripts that
2315 check for these errors to help keep them out of future releases.
2320 <title>Testing by testers</title>
2322 For any program that depends on user interactivity, many bugs
2323 will only be uncovered through testing by users actually clicking
2324 the keys and pressing the mouse buttons. For this you need
2325 testers and as many as possible.
2329 The most difficult part of testing is finding testers. It's
2330 usually a good tactic to post a message to a relevant mailing
2331 list or news group announcing a specific proposed release date
2332 and outlining the functionality of your program. If you put some
2333 time into the announcement, you are sure to get a few responses.
2337 The second most difficult part of testing is
2338 <emphasis>keeping</emphasis> your testers and keeping them
2339 actively involved in the testing process. Fortunately, there are
2340 some tried and true tactics that can applied toward this end:
2347 <term>Make things simple for your testers</term>
2349 <para>Your testers are doing you a favor so make it as easy as
2350 possible for them. This means that you should be careful to
2351 package your software in a way that is easy to find, unpack,
2352 install, and uninstall. This also means you should explain
2353 what you are looking for to each tester and make the means for
2354 reporting bugs simple and well established. The key is to
2355 provide as much structure as possible to make your testers'
2356 jobs easy and to maintain as much flexibility as possible for
2357 those that want to do things a little differently.</para>
2362 <term>Be responsive to your testers</term>
2364 <para>When your testers submit bugs, respond to them and
2365 respond quickly. Even if you are only responding to tell them
2366 that the bug has already been fixed, quick and consistent
2367 responses make them feel like their work is heard, important,
2368 and appreciated.</para>
2373 <term>Thank your testers</term>
2375 <para>Thank them personally each time they send you
2376 patch. Thank them publicly in the documentation and the about
2377 section of your program. You appreciate your testers and your
2378 program would not be possible without their help. Make sure
2379 they know it. Publicly, pat them on the back to make sure the rest of
2380 the world knows it too. It will be appreciated more than you
2391 <!-- Section2: support -->
2393 <sect2 id="support">
2394 <title>Setting up Support Infrastructure</title>
2397 While testing is important, the large part of your interactions
2398 and responsibility to your users falls under the category of
2399 support. The best way to make sure your users are adequately
2400 supported in using your program is to set up a good infrastructure
2401 for this purpose so that your developers and users help each other
2402 and less of the burden falls on you. This way, people will also
2403 get quicker and better responses to their questions. This
2404 infrastructure comes in several major forms:
2408 <title>Documentation</title>
2410 It should not come as any surprise that the key element to any
2411 support infrastructure is good documentation. This topic was
2412 largely covered in <xref linkend="documentation"> and will not be
2417 <sect3 id="mailinglists">
2418 <title>Mailing lists</title>
2420 Aside from documentation, effective mailing lists will be your
2421 greatest tool in providing user support. Running a mailing list
2422 well is more complicated than installing mailing list software
2427 <title>Separate lists</title>
2430 A good idea is too separate your user and development mailing
2431 lists (perhaps into project-user@host and project-devel@host)
2432 and enforce the division. If people post a development question
2433 onto -user, politely ask them to repost it onto -devel and vise
2434 versa. Subscribe yourself to both groups and encourage all
2435 primarily developers to do the same.
2439 This system provides so that no one person is stuck doing all of
2440 the support work and works so that users learn more about the
2441 program, they can help newer users with their questions.
2446 <title>Choose mailing list software well</title>
2448 Please don't make the selection of mailing list software
2449 impulsively. Please consider easy accessibility by users without
2450 a lot of technical experience so you want to be as easy as
2451 possible. Web accessibility to an archive of the list is also
2456 The two biggest free software mailing list programs are <ulink
2457 url="http://www.greatcircle.com/majordomo/">majordomo</ulink>
2458 and <ulink url="http://www.list.org/">GNU Mailman</ulink>. A
2459 long time advocate of majordomo, I would now recommend any
2460 project choose GNU Mailman. It fulfills the criteria listed
2461 above and makes it easier. It provides a good mailing
2462 list program for a free software project maintainer as opposed
2463 to a good mailing list application for a mailing list
2468 There are other things you want to take into consideration in
2469 setting up your list. If it is possible to gate your mailing
2470 lists to Usenet and provide it in digest form as well as
2471 making them accessible on the web, you will please some users
2472 and work to make the support infrastructure slightly more
2479 <title>Other support ideas</title>
2482 A mailing list and accessible documentation are far from all you
2483 can do to set up good user support infrastructure. Be
2484 creative. If you stumble across something that works well, email me
2485 and I'll include it here.
2489 <title>Make your self accessible</title>
2491 You can not list too few methods to reach you. If you hang out
2492 in an <acronym>IRC</acronym> channel, don't hesitate to list it
2493 in your projects documentation. List email and snailmail
2494 addresses, and ways to reach you via <acronym>ICQ</acronym>,
2495 <acronym>AIM</acronym>, or Jabber if they apply.
2500 <title>Bug management software</title>
2502 For many large software projects, use of bug management software
2503 is essential to keep track of which bugs have been fixed, which
2504 bugs have not been fixed, and which bugs are being fixed by
2505 which people. Debian uses the <ulink
2506 url="http://bugs.debian.org">Debian Bug Tracking System</ulink>
2507 (<acronym>BTS</acronym>) although it may not be best choice for
2508 every project (it seems to currently be buckling under its own
2509 weight) As well as a damn good web browser, the Mozilla project
2510 has spawned a sub-project resulting in a bug tracking system
2512 url="http://www.mozilla.org/projects/bugzilla/">bugzilla</ulink>
2513 which has become extremely possible and which I like a lot.
2517 These systems (and others like them) can be unwieldy so
2518 developers should be careful to not spend more time on the bug
2519 tracking system than on the bugs or the projects themselves. If
2520 a project continues to grow, use of a bug tracking system can
2521 provide an easy standard avenue for users and testers to report
2522 bugs and for developers and maintainers to fix them and track
2523 them in an orderly fashion.
2529 <!-- Section2: releasing -->
2531 <sect2 id="releasing">
2532 <title>Releasing Your Program</title>
2535 As mentioned earlier in the HOWTO, the first rule of releasing is,
2536 <emphasis>release something useful.</emphasis> Non-working or
2537 not-useful software will not attract anyone to your
2538 project. People will be turned off of your project and will be likely
2539 to simply gloss over it next time they see a new version
2540 announced. Half-working software, if useful, will intrigue people,
2541 whet their appetites for versions to come, and encourage them to
2542 join the development process.
2546 <title>When to release</title>
2549 Making the decision to release your software for the first time
2550 is an incredibly important and incredibly stressful decision. But
2551 it needs to done. My advice is to try and make something that
2552 is complete enough to be usable and incomplete enough to allow
2553 for flexibility and room for imagination by your future
2554 developers. It's not an easy decision. Ask for help on a local
2555 Linux User Group mailing list or from a group of developer
2560 One tactic is to first do an <quote>alpha</quote> or
2561 <quote>beta</quote> release as described below in <xref
2562 linkend="alphabeta">. However, most of the guidelines described
2567 <emphasis>When you feel in your gut that it is time and you feel
2568 you've weighed the situation well several times, cross your
2569 fingers and take the plunge.</emphasis>
2573 After you've released for the first time, knowing when to release
2574 becomes less stressful, but just as difficult to gauge. I like
2575 the criteria offered by Robert Krawitz in his article, <ulink
2576 url="http://www.advogato.org/article/196.html"><quote>Free
2577 Software Project Management</quote></ulink> for maintaining a
2578 good release cycle. He recommends that you ask yourself,
2579 <quote>does this release...</quote>
2585 <para>Contain sufficient new functionality or bug fixes to be
2586 worth the effort.</para>
2590 <para>Be spaced sufficiently far apart to allow the user time
2591 to work with the latest release.</para>
2595 <para>Be sufficiently functional so that the user can get work
2596 done (quality).</para>
2602 If the answer is yes to all of these questions, its probably time
2603 for a release. If in doubt, remember that asking for advice can't
2609 <title>How to release</title>
2612 If you've followed the guidelines described in this HOWTO up
2613 until this point, the mechanics of doing a release are going to
2614 be the easy part of releasing. If you have set up consistent
2615 distribution locations and the other infrastructure described in
2616 the preceding sections, releasing should be as simple as building
2617 the package, checking it once over, and uploading it into the
2618 appropriate place and then making your website reflect the
2623 <sect3 id="alphabeta">
2624 <title>Alpha, beta, and development releases</title>
2627 When contemplating releases, it worth considering the fact that
2628 not every release needs to be a full numbered release. Software
2629 users are accustomed to pre-releases but you must be careful to
2630 label these releases accurately or they will cause more problems then
2635 The observation is often made that many free software developers
2636 seem to be confused about the release cycle. <quote><ulink
2637 url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
2638 Projects the Open Source Way</ulink></quote> suggests that you memorize
2639 the phrase, <quote>Alpha is not Beta. Beta is not Release</quote>
2640 and I'd agree that tis is a probably a good idea.
2647 <term>alpha releases</term>
2649 <para>Alpha software is feature-complete but sometimes only
2650 partially functional.</para>
2652 <para>Alpha releases are expected to be unstable, perhaps a
2653 little unsafe, but definitely usable. They
2654 <emphasis>can</emphasis> have known bugs and kinks that have
2655 yet to be worked out. Before releasing an alpha, be sure to
2656 keep in mind that <emphasis>alpha releases are still
2657 releases</emphasis> and people are not going to be expecting a
2658 nightly build from the CVS source. An alpha should work and
2659 have minimal testing and bug fixing already finished.</para>
2664 <term>beta releases</term>
2666 <para>Beta software is feature-complete and functional, but is
2667 in the testing cycle and still has a few bugs left to be
2670 <para>Beta releases are general expected to be usable and
2671 slightly unstable, although definitely <emphasis>not
2672 unsafe.</emphasis> Beta releases usually preclude a full
2673 release by under a month. They can contain small known bugs
2674 but no major ones. All major functionality should be fully
2675 implemented although the exact mechanics can still be worked
2676 out. Beta releases are great tool to whet the appetites of
2677 potential users by giving them a very realistic view of where
2678 your project is going to be in the very near future and can
2679 help keep interest by giving people
2680 <emphasis>something.</emphasis></para>
2685 <term>development releases</term>
2687 <para><quote>Development release</quote> is much a more vague
2688 term than <quote>alpha</quote> or <quote>beta</quote>. I
2689 usually choose to reserve the term for discussion of a
2690 development branch although there are other ways to use the
2691 term. So many in fact, that I feel the term has been
2692 cheapened. The popular window manager <ulink
2693 url="http://www.enlightenment.org">Enlightenment</ulink> has
2694 released <emphasis>nothing but</emphasis> development
2695 releases. Most often, the term is used to describe releases
2696 that are not even alpha or beta and if I were to release a
2697 pre-alpha version of a piece of software in order to keep
2698 interest in my project alive, this is probably how I would
2699 have to label it.</para>
2709 <!-- Section2: announcing -->
2711 <sect2 id="announcing">
2712 <title>Announcing Your Project</title>
2715 Well, you've done it. You've (at least for the purposes of this
2716 HOWTO) designed, built, and released your free software
2717 project. All that is left is for you to tell the world so they
2718 know to come and try it out and hopefully jump on board with
2719 development. If everything is in order as described above, this
2720 will be a quick and painless process. A quick announcement is all
2721 that it takes to put yourself on the free software community's
2726 <title>Mailing lists and Usenet</title>
2728 <para>Announce your software on Usenet's <ulink
2729 url="news:comp.os.linux.announce">comp.os.linux.announce</ulink>. If
2730 you only announce your software in two places, have it be c.o.l.a
2731 and freshmeat.</para>
2734 However, email is still the way that most people on the Internet
2735 get their information. Its a good idea to send a message
2736 announcing your program to any relevant mailing list you know of
2737 and any other relevant Usenet discussion groups.</para>
2739 <para>Karl Fogel recommends that use you simple subject
2740 describing the fact that the message is an announcement, the name
2741 of the program, the version, and a half-line long description of
2742 its functionality. This way, any interested user or developer
2743 will be immediately attracted to your announcement. Fogel's
2747 <screen>Subject: ANN: aub 1.0, a program to assemble Usenet binaries</screen>
2750 The rest of the email should describe the programs functionality
2751 quickly and concisely in no more than two paragraphs and should
2752 provide links to the projects webpage and direct links to
2753 downloads for those that want to try it right away. This form
2754 will work for both Usenet and mailing list posts.
2758 You should repeat this announcement process consistently in the
2759 same locations for each subsequent release.
2764 <title>freshmeat.net</title>
2766 Mentioned earlier in <xref linkend="evalwhere">, in today's free
2767 software community, announcements of your project on freshmeat
2768 are almost more important than announcements on mailing lists.
2772 Visit the <ulink url="http://freshmeat.net">freshmeat.net
2773 website</ulink> or their <ulink
2774 url="http://freshmeat.net/add-project/">submit project
2775 page</ulink> to post your project onto their site and into their
2776 database. In addition to a large website, freshmeat provides a
2777 daily newsletter that highlights all the days releases and
2778 reaches a huge audience (I personally skim it every night for any
2779 interesting new releases).
2784 <title>Project Mailing List</title>
2786 <para>If you've gone ahead and created mailing lists for your
2787 project, you should always announce new versions on these
2788 lists. I've found that for many projects, users request a very
2789 low-volume announce only mailing list to be notified when new
2790 versions are released. freshmeat.net now allows users to subscribe
2791 to a particular project so they receive emails every time a new
2792 version is announced through their system. It's free and it can
2793 stand in for an announce-only mailing list. In my opinion, it
2802 <title>Printed Books</title>
2807 <surname>Fogel</surname>
2808 <firstname>Karl</firstname>
2811 <title>Open Source Development with CVS</title>
2814 <publishername>Coriolois Open Press</publishername>
2816 <pubdate>1999</pubdate>
2818 <isbn>1-57610-490-7</isbn>
2822 Fogel's <quote>guide to using CVS in the free software
2823 world</quote> is much more than its subtitle. In the publisher's
2824 own words: <quote><emphasis>Open Source Development with
2825 CVS</emphasis> is one of the first books available that teaches
2826 you development and implementation of Open Source
2827 software.</quote> It also includes the best reference and
2828 tutorial to CVS I have ever seen. It is the book that was
2829 <emphasis>so good</emphasis> that it prompted me to write this
2830 HOWTO because I thought the role it tried to serve was so
2831 important and useful. Please check it or buy it if you can and
2832 are seriously interested in running a free software project.
2835 <para>In May of 2003, the entire book under the GPL. You can
2836 find the full text of the book <ulink
2837 url="http://cvsbook.red-bean.com/">here</ulink>.</para>
2845 <surname>Lessig</surname>
2846 <firstname>Lawrence</firstname>
2849 <title>Code and Other Laws of Cyberspace</title>
2852 <publishername>Basic Books</publishername>
2854 <pubdate>2000</pubdate>
2856 <isbn>0-465-03913-8</isbn>
2860 While it only briefly talks about free software (and does it by
2861 tiptoeing around the free software/open source issue with the
2862 spineless use of the term <quote>open code</quote> that only a
2863 lawyer could coin), Lessig's book is brilliant. Written by a
2864 lawyer, it talks about how regulation on the Internet is not
2865 done with law, but with the code itself and how the nature of
2866 the code will determine the nature of future freedoms. In
2867 addition to being a quick and enjoyable read, it gives some
2868 cool history and describes how we <emphasis>need</emphasis>
2869 free software in a way more powerfully than anything I've read
2871 url="http://www.gnu.org/philosophy/right-to-read.html">RMS's
2872 <quote>Right to Read.</quote></ulink>
2881 <surname>Raymond</surname>
2882 <firstname>Eric</firstname>
2885 <title>The Cathedral and the Bazaar</title>
2886 <subtitle>Musings on Linux and Open Source by an Accidental Revolutionary</subtitle>
2889 <publishername>O'Reilly</publishername>
2891 <pubdate>1999</pubdate>
2893 <isbn>1-56592-724-9</isbn>
2896 Although I have to honestly say that I am not the ESR fan that
2897 I used to be, this book proved invaluable in getting me where I
2898 am today. The essay that gives the book its title does a good
2899 job of sketching the free software process and does an an
2900 amazing job of making an argument for free software/open source
2901 development as a road to better software. The rest of the book
2902 has other of ESR's articles, which for the most part are posted
2903 on his website. Still, it's nice thing to own in hard copy and
2904 something that every free software/open source hacker should
2913 <title>Web-Accessible Resources</title>
2916 This is a list of the web resources pertaining to this HOWTO that
2917 I've found most helpful in compiling this information. If you know
2918 of others that would help, please don't hesitate to email me at
2919 <email>mako@atdot.cc</email> and we can look into getting it
2920 added to the list and represented in the HOWTO.
2924 I'd recommend that any free software developer (or potential one)
2925 skim through these sites because they have each have a lot to say.
2932 <surname>Dafermos</surname>
2933 <firstname>George</firstname>
2934 <othername>N</othername>
2937 <title><ulink url="http://firstmonday.org/issues/issue6_11/dafermos/">Management and Virtual Decentralized Networks: The Linux Project</ulink></title>
2940 <para>Since the paper includes its own abstract, I thought I
2941 would include it here verbatim:</para>
2943 <para><blockquote><para>This paper examines the latest of
2944 paradigms - the Virtual Network(ed) Organisation - and whether
2945 geographically dispersed knowledge workers can virtually
2946 collaborate for a project under no central
2947 planning. Co-ordination, management and the role of knowledge
2948 arise as the central areas of focus. The Linux Project and its
2949 development model are selected as a case of analysis and the
2950 critical success factors of this organisational design are
2951 identified. The study proceeds to the formulation of a
2952 framework that can be applied to all kinds of virtual
2953 decentralised work and concludes that value creation is
2954 maximized when there is intense interaction and uninhibited
2955 sharing of information between the organisation and the
2956 surrounding community. Therefore, the potential success or
2957 failure of this organisational paradigm depends on the degree
2958 of dedication and involvement by the surrounding
2959 community.</para></blockquote></para>
2961 <para>This paper was referred to me in my capacity as author of
2962 this HOWTO and I was very impressed. It's written by a graduate
2963 student in management and I think it succeeds at evaluating the
2964 Linux project as an example of a new paradigm in management--one
2965 that <emphasis>you</emphasis> will be be placing yourself at the
2966 center of in your capacity as maintainer of a free software
2969 <para>As a developer trying to control an application and guide
2970 it to success in the free software world, I'm not sure how
2971 useful Dafermos's argument is. It does however, provide a
2972 theoretical justification for my HOWTO--free software project
2973 management <emphasis>is</emphasis> a different creature than
2974 proprietary software project management. If you are interested
2975 in the conceptual and theoretical ways that free software
2976 project management differs from other types of management, this
2977 is a great paper to read. If this paper answers questions of
2978 <quote>how?</quote>, Dafermos answers the (more difficult to
2979 defend) questions of <quote>why?</quote> and does a very good
2990 <surname>Gabriel</surname>
2991 <firstname>Richard</firstname>
2995 url="http://www.jwz.org/doc/worse-is-better.html">The Rise of
2996 <quote>Worse is Better</quote></ulink></title>
3000 A well written article although I think the title may have
3001 confused as many people as the rest of the essay helped. It
3002 offers a good description of how to design programs that will
3003 succeed and stay maintainable as they grow.
3012 <surname>Manley</surname>
3013 <firstname>Montey</firstname>
3017 url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
3018 Projects the Open Source Way</ulink></title>
3021 <publishername><ulink
3022 url="http://www.linuxprogramming.com">Linux
3023 Programming</ulink></publishername>
3025 <pubdate>Oct 31, 2000</pubdate>
3029 In one of the better articles on the subject that I've read,
3030 Monty sums up some of the major points I touch on including:
3031 starting a project, testing, documentation, organizing a team and
3032 leadership, and several other topics. While more opinionated that
3033 I try to be, I think its an important article that I found very
3034 helpful in writing this HOWTO. I've tried to cite him in
3035 the places where I borrowed from him most.
3039 I have problems much of this piece and I recommend you read
3040 <xref linkend="krawitz"> at the same time you read Monty's
3041 article for a good critique.
3047 <biblioentry id="esrhowto">
3050 <surname>Raymond</surname>
3051 <firstname>Eric</firstname>
3052 <othername>Steven</othername>
3055 <title><ulink url="http://www.tldp.org/HOWTO/Software-Release-Practice-HOWTO/index.html">Software Release Practice HOWTO</ulink></title>
3059 <para>At first glance, ESR's release practice HOWTO seems to
3060 share a lot of terrain with this document. Upon closer
3061 examination, the differences become apparent but they are
3062 closely related. His document, read in conjunction with mine,
3063 will give a reader a good picture of how to go about managing a
3064 project. ESR's HOWTO goes into a bit more detail on how to write
3065 and what languages to write in. He tends to give more specific
3066 instructions and checklists (<quote>name this file this, not
3067 this</quote>) while this HOWTO speaks more conceptually. There
3068 are several sections that are extremely similar. It's also
3069 <emphasis>much</emphasis> shorter.</para>
3071 <para>My favorite quote from his HOWTO is: <quote>"Managing a
3072 project well when all the participants are volunteers presents
3073 some unique challenges. This is too large a topic to cover in a
3074 HOWTO.</quote> Oh really? Perhaps I just do a poor job.</para>
3081 <biblioentry id="cvsbestpractices">
3084 <surname>Venugopalan</surname>
3085 <firstname>Vivek</firstname>
3088 <title><ulink url="http://www.magic-cauldron.com/cm/cvs-bestpractices/index.html">CVS Best Practices</ulink></title>
3092 <para>Venugopalan provides one of the best essays on
3093 effective use of CVS that I've come across. It is written for
3094 people who already have a good knowledge of CVS. In the chapter
3095 on branching, he describes when and how to branch but gives no
3096 information on what CVS commands you should use to do this. This
3097 is fine (technical CVS HOWTO have been written) but CVS newbies
3098 will want to spend some time with Fogel's reference before they
3099 will find this one very useful.</para>
3101 <para>Venugopalan creates checklists of things to do before,
3102 after, and around releases. It's definitely worth a read through
3103 as most of his ideas will save tons of developer head aches over
3104 any longer period of time.</para>
3113 <title>Advogato Articles</title>
3116 I've found that one of the best resources that any free software
3117 developer has at his or her disposal is Advogato.org. If you haven't
3118 yet had a chance to visit <ulink url="http://www.advogato.org">the
3119 website</ulink>, do.
3123 I have spent a huge amount of time on Advogato and I've gone
3124 through and provided links to the articles that I think might be
3125 of particular interest to anyone reading this HOWTO. I think that
3126 skimming through these links can be helpful and I promise that if
3127 you do, you'll learn a lot. You will learn that my idea of how a
3128 free software project should be run is not the
3129 <emphasis>only</emphasis> idea. I think that's important.
3133 If nothing else, there is <emphasis>way</emphasis> more
3134 information on that website than I could ever fit into, or
3135 reference from this HOWTO. I have listed what I think are the most
3136 relevant articles here with short descriptions that I've written.
3143 <surname>Hindle</surname>
3144 <firstname>Stephen</firstname>
3147 <title><ulink url="http://www.advogato.org/article/262.html">'Best Practices' for Open Source?</ulink></title>
3150 <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
3152 <pubdate>March 21, 2001</pubdate>
3156 Touching mostly on programming practice (as most articles on
3157 the subject usually do), the article talks a little about
3158 project management (<quote>Use it!</quote>) and a bit about
3159 communication within a free software project.
3168 <surname>Cohen</surname>
3169 <firstname>Bram</firstname>
3173 url="http://www.advogato.org/article/258.html"></ulink>How to
3174 Write Maintainable Code</title>
3177 <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
3179 <pubdate>March 15, 2001</pubdate>
3183 This article touches upon the "writing maintainable code"
3184 discussion that I try hard to avoid in my HOWTO. It's one of
3185 the better (and most diplomatic) articles on the subject that
3191 <biblioentry id="krawitz">
3194 <surname>Krawitz</surname>
3195 <firstname>Robert</firstname>
3198 <title><ulink url="http://www.advogato.org/article/196.html">Free
3199 Source Project Management</ulink></title>
3202 <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
3204 <pubdate>November 4, 2000</pubdate>
3208 This article made me happy because it challenged many of the
3209 problems that I had with Monty's article on <ulink
3210 url="http://www.linuxprogramming.com">LinuxProgramming</ulink>. The
3211 author argues that Monty calls simply for the application of
3212 old (proprietary software) project management techniques in
3213 free software projects instead of working to come up with
3214 something new. I found his article to be extremely well thought
3215 out and I think it's an essential read for any free software
3225 <surname>Martins</surname>
3226 <firstname>Lalo</firstname>
3229 <title><ulink url="http://www.advogato.org/article/128.html">Ask
3230 the Advogatos: why do Free Software projects
3231 fail?</ulink></title>
3234 <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
3236 <pubdate>July 20, 2000</pubdate>
3240 While the article is little more than a question, reading the
3241 answers to this question offered by Advogato's readers can
3242 help. In a lot of ways, this HOWTO acts as my answer to the
3243 questions posed in this article but there are others, many of
3244 which might take issue with whats is in this HOWTO. It's worth
3254 <surname>Burley</surname>
3255 <firstname>David</firstname>
3259 url="http://www.advogato.org/article/107.html">In-Roads to Free
3260 Software Development</ulink></title>
3263 <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
3265 <pubdate>June 14, 2000</pubdate>
3269 This document was written as a response to <ulink
3270 url="http://www.advogato.org/article/72.html">another Advogato
3271 article</ulink>. Although not about running a project, this
3272 describes some of the ways that you can get started with free
3273 software development without starting a project. I think this
3274 is an important article. If you are interested in becoming
3275 involved with free software, this article showcases some of the
3276 ways that you can do this without actually starting a project
3277 (something that I hope this HOWTO has demonstrated is not to be
3287 <surname>Moorman</surname>
3288 <firstname>Jacob</firstname>
3291 <title><ulink url="http://www.advogato.org/article/72.html">Importance of
3292 Non-Developer Supporters in Free Software</ulink><title></title>
3295 <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
3297 <pubdate>April 16, 2000</pubdate>
3301 Moorman's is a short article but it brings up some good
3302 points. The comment reminding developers to thank their testers
3303 and end-users is invaluable and oft-forgotten.
3312 <surname>Orchard</surname>
3313 <firstname>Leslie</firstname>
3316 <title><ulink url="http://www.advogato.org/article/67.html">On
3317 Naming an Open Source Project</ulink></title>
3320 <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
3322 <pubdate>April 12, 2000</pubdate>
3326 I didn't even have a section on project naming in this HOWTO
3327 (See <xref linkend="naming">) until Leslie Orchard's article
3328 reminded me of it. Thanks to Leslie for writing this article!
3337 <surname>Allen</surname>
3338 <firstname>David</firstname>
3341 <title><ulink url="http://www.advogato.org/article/40.html">Version Numbering Madness</ulink></title>
3344 <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
3346 <pubdate>February 28, 2000</pubdate>
3350 In this article, David Allen challenges the whole
3351 <quote>Major.Minor.Patch</quote> version numbering scheme. Its
3352 good to read this as you read <xref
3353 linkend="chooseversioning">. I liked the article and it
3354 describes some of the projects that I bring up in my discussion
3355 of version numbering.
3365 <title>GNU Free Documentation License</title>
3367 Copyright (C) 2000, 2001, 2002 Free Software Foundation,
3368 <abbrev>Inc.</abbrev> 51 Franklin <abbrev>St</abbrev>, Fifth Floor,
3369 Boston, <abbrev>MA</abbrev> 02110-1301 <abbrev
3370 role="initialism">USA</abbrev>. Everyone is permitted to copy and
3371 distribute verbatim copies of this license document, but changing it is
3374 <bridgehead id="Preamble" renderas="sect1">
3378 The purpose of this License is to make a manual, textbook, or other
3379 functional and useful document "free" in the sense of freedom: to assure
3380 everyone the effective freedom to copy and redistribute it, with or
3381 without modifying it, either commercially or noncommercially.
3382 Secondarily, this License preserves for the author and publisher a way to
3383 get credit for their work, while not being considered responsible for
3384 modifications made by others.
3387 This License is a kind of "copyleft", which means that derivative works of
3388 the document must themselves be free in the same sense. It complements
3389 the GNU General Public License, which is a copyleft license designed for
3393 We have designed this License in order to use it for manuals for free
3394 software, because free software needs free documentation: a free program
3395 should come with manuals providing the same freedoms that the software
3396 does. But this License is not limited to software manuals; it can be used
3397 for any textual work, regardless of subject matter or whether it is
3398 published as a printed book. We recommend this License principally for
3399 works whose purpose is instruction or reference.</para>
3400 <bridgehead id="Definitions" renderas="sect1">
3401 1. APPLICABILITY AND DEFINITIONS
3404 This License applies to any manual or other work, in any medium, that
3405 contains a notice placed by the copyright holder saying it can be
3406 distributed under the terms of this License. Such a notice grants a
3407 world-wide, royalty-free license, unlimited in duration, to use that work
3408 under the conditions stated herein. The "Document", below, refers to any
3409 such manual or work. Any member of the public is a licensee, and is
3410 addressed as "you". You accept the license if you copy, modify or
3411 distribute the work in a way requiring permission under copyright
3415 A "Modified Version" of the Document means any work containing the
3416 Document or a portion of it, either copied verbatim, or with modifications
3417 and/or translated into another language.
3420 A "Secondary Section" is a named appendix or a front-matter section of the
3421 Document that deals exclusively with the relationship of the publishers or
3422 authors of the Document to the Document's overall subject (or to related
3423 matters) and contains nothing that could fall directly within that overall
3424 subject. (Thus, if the Document is in part a textbook of mathematics, a
3425 Secondary Section may not explain any mathematics.) The relationship
3426 could be a matter of historical connection with the subject or with
3427 related matters, or of legal, commercial, philosophical, ethical or
3428 political position regarding them.
3431 The "Invariant Sections" are certain Secondary Sections whose titles are
3432 designated, as being those of Invariant Sections, in the notice that says
3433 that the Document is released under this License. If a section does not
3434 fit the above definition of Secondary then it is not allowed to be
3435 designated as Invariant. The Document may contain zero Invariant
3436 Sections. If the Document does not identify any Invariant Sections then
3440 The "Cover Texts" are certain short passages of text that are listed, as
3441 Front-Cover Texts or Back-Cover Texts, in the notice that says that the
3442 Document is released under this License. A Front-Cover Text may be at
3443 most 5 words, and a Back-Cover Text may be at most 25 words.
3446 A "Transparent" copy of the Document means a machine-readable copy,
3447 represented in a format whose specification is available to the general
3448 public, that is suitable for revising the document straightforwardly with
3449 generic text editors or (for images composed of pixels) generic paint
3450 programs or (for drawings) some widely available drawing editor, and that
3451 is suitable for input to text formatters or for automatic translation to a
3452 variety of formats suitable for input to text formatters. A copy made in
3453 an otherwise Transparent file format whose markup, or absence of markup,
3454 has been arranged to thwart or discourage subsequent modification by
3455 readers is not Transparent. An image format is not Transparent if used
3456 for any substantial amount of text. A copy that is not "Transparent" is
3460 Examples of suitable formats for Transparent copies include plain ASCII
3461 without markup, Texinfo input format, LaTeX input format, SGML or XML
3462 using a publicly available DTD, and standard-conforming simple HTML,
3463 PostScript or PDF designed for human modification. Examples of
3464 transparent image formats include PNG, XCF and JPG. Opaque formats
3465 include proprietary formats that can be read and edited only by
3466 proprietary word processors, SGML or XML for which the DTD and/or
3467 processing tools are not generally available, and the machine-generated
3468 HTML, PostScript or PDF produced by some word processors for output
3472 The "Title Page" means, for a printed book, the title page itself, plus
3473 such following pages as are needed to hold, legibly, the material this
3474 License requires to appear in the title page. For works in formats which
3475 do not have any title page as such, "Title Page" means the text near the
3476 most prominent appearance of the work's title, preceding the beginning of
3477 the body of the text.
3480 A section "Entitled XYZ" means a named subunit of the Document whose title
3481 either is precisely XYZ or contains XYZ in parentheses following text that
3482 translates XYZ in another language. (Here XYZ stands for a specific
3483 section name mentioned below, such as "Acknowledgements", "Dedications",
3484 "Endorsements", or "History".) To "Preserve the Title" of such a section
3485 when you modify the Document means that it remains a section "Entitled
3486 XYZ" according to this definition.
3489 The Document may include Warranty Disclaimers next to the notice which
3490 states that this License applies to the Document. These Warranty
3491 Disclaimers are considered to be included by reference in this License,
3492 but only as regards disclaiming warranties: any other implication that
3493 these Warranty Disclaimers may have is void and has no effect on the
3494 meaning of this License.
3496 <bridgehead id="VerbatimCopying" renderas="sect1">
3500 You may copy and distribute the Document in any medium, either
3501 commercially or noncommercially, provided that this License, the copyright
3502 notices, and the license notice saying this License applies to the
3503 Document are reproduced in all copies, and that you add no other
3504 conditions whatsoever to those of this License. You may not use technical
3505 measures to obstruct or control the reading or further copying of the
3506 copies you make or distribute. However, you may accept compensation in
3507 exchange for copies. If you distribute a large enough number of copies
3508 you must also follow the conditions in section 3.
3511 You may also lend copies, under the same conditions stated above, and you
3512 may publicly display copies.
3514 <bridgehead id="QuantityCopying" renderas="sect1">
3515 3. COPYING IN QUANTITY
3518 If you publish printed copies (or copies in media that commonly have
3519 printed covers) of the Document, numbering more than 100, and the
3520 Document's license notice requires Cover Texts, you must enclose the
3521 copies in covers that carry, clearly and legibly, all these Cover Texts:
3522 Front-Cover Texts on the front cover, and Back-Cover Texts on the back
3523 cover. Both covers must also clearly and legibly identify you as the
3524 publisher of these copies. The front cover must present the full title
3525 with all words of the title equally prominent and visible. You may add
3526 other material on the covers in addition. Copying with changes limited to
3527 the covers, as long as they preserve the title of the Document and satisfy
3528 these conditions, can be treated as verbatim copying in other
3532 If the required texts for either cover are too voluminous to fit legibly,
3533 you should put the first ones listed (as many as fit reasonably) on the
3534 actual cover, and continue the rest onto adjacent pages.
3537 If you publish or distribute Opaque copies of the Document numbering more
3538 than 100, you must either include a machine-readable Transparent copy
3539 along with each Opaque copy, or state in or with each Opaque copy a
3540 computer-network location from which the general network-using public has
3541 access to download using public-standard network protocols a complete
3542 Transparent copy of the Document, free of added material. If you use the
3543 latter option, you must take reasonably prudent steps, when you begin
3544 distribution of Opaque copies in quantity, to ensure that this Transparent
3545 copy will remain thus accessible at the stated location until at least one
3546 year after the last time you distribute an Opaque copy (directly or
3547 through your agents or retailers) of that edition to the public.
3550 It is requested, but not required, that you contact the authors of the
3551 Document well before redistributing any large number of copies, to give
3552 them a chance to provide you with an updated version of the
3555 <bridgehead id="Modifications" renderas="sect1">
3559 You may copy and distribute a Modified Version of the Document under the
3560 conditions of sections 2 and 3 above, provided that you release the
3561 Modified Version under precisely this License, with the Modified Version
3562 filling the role of the Document, thus licensing distribution and
3563 modification of the Modified Version to whoever possesses a copy of it.
3564 In addition, you must do these things in the Modified Version:
3566 <orderedlist numeration="upperalpha">
3569 Use in the Title Page (and on the covers, if any) a title distinct
3570 from that of the Document, and from those of previous versions (which
3571 should, if there were any, be listed in the History section of the
3572 Document). You may use the same title as a previous version if the
3573 original publisher of that version gives permission.
3578 List on the Title Page, as authors, one or more persons or entities
3579 responsible for authorship of the modifications in the Modified
3580 Version, together with at least five of the principal authors of the
3581 Document (all of its principal authors, if it has fewer than five),
3582 unless they release you from this requirement.
3587 State on the Title page the name of the publisher of the Modified
3588 Version, as the publisher.
3593 Preserve all the copyright notices of the Document.
3598 Add an appropriate copyright notice for your modifications adjacent to
3599 the other copyright notices.
3604 Include, immediately after the copyright notices, a license notice
3605 giving the public permission to use the Modified Version under the
3606 terms of this License, in the form shown in the Addendum below.
3611 Preserve in that license notice the full lists of Invariant Sections
3612 and required Cover Texts given in the Document's license notice.
3617 Include an unaltered copy of this License.
3622 Preserve the section Entitled "History", Preserve its Title, and add
3623 to it an item stating at least the title, year, new authors, and
3624 publisher of the Modified Version as given on the Title Page. If
3625 there is no section Entitled "History" in the Document, create one
3626 stating the title, year, authors, and publisher of the Document as
3627 given on its Title Page, then add an item describing the Modified
3628 Version as stated in the previous sentence.
3633 Preserve the network location, if any, given in the Document for
3634 public access to a Transparent copy of the Document, and likewise the
3635 network locations given in the Document for previous versions it was
3636 based on. These may be placed in the "History" section. You may omit
3637 a network location for a work that was published at least four years
3638 before the Document itself, or if the original publisher of the
3639 version it refers to gives permission.
3644 For any section Entitled "Acknowledgements" or "Dedications", Preserve
3645 the Title of the section, and preserve in the section all the
3646 substance and tone of each of the contributor acknowledgements and/or
3647 dedications given therein.
3652 Preserve all the Invariant Sections of the Document, unaltered in
3653 their text and in their titles. Section numbers or the equivalent are
3654 not considered part of the section titles.
3659 Delete any section Entitled "Endorsements". Such a section may not be
3660 included in the Modified Version.
3665 Do not retitle any existing section to be Entitled "Endorsements" or
3666 to conflict in title with any Invariant Section.
3671 Preserve any Warranty Disclaimers.
3676 If the Modified Version includes new front-matter sections or appendices
3677 that qualify as Secondary Sections and contain no material copied from the
3678 Document, you may at your option designate some or all of these sections
3679 as invariant. To do this, add their titles to the list of Invariant
3680 Sections in the Modified Version's license notice. These titles must be
3681 distinct from any other section titles.
3684 You may add a section Entitled "Endorsements", provided it contains
3685 nothing but endorsements of your Modified Version by various parties--for
3686 example, statements of peer review or that the text has been approved by
3687 an organization as the authoritative definition of a standard.
3690 You may add a passage of up to five words as a Front-Cover Text, and a
3691 passage of up to 25 words as a Back-Cover Text, to the end of the list of
3692 Cover Texts in the Modified Version. Only one passage of Front-Cover Text
3693 and one of Back-Cover Text may be added by (or through arrangements made
3694 by) any one entity. If the Document already includes a cover text for the
3695 same cover, previously added by you or by arrangement made by the same
3696 entity you are acting on behalf of, you may not add another; but you may
3697 replace the old one, on explicit permission from the previous publisher
3698 that added the old one.
3701 The author(s) and publisher(s) of the Document do not by this License give
3702 permission to use their names for publicity for or to assert or imply
3703 endorsement of any Modified Version.
3705 <bridgehead id="Combining" renderas="sect1">
3706 5. COMBINING DOCUMENTS
3709 You may combine the Document with other documents released under this
3710 License, under the terms defined in section 4 above for modified versions,
3711 provided that you include in the combination all of the Invariant Sections
3712 of all of the original documents, unmodified, and list them all as
3713 Invariant Sections of your combined work in its license notice, and that
3714 you preserve all their Warranty Disclaimers.
3717 The combined work need only contain one copy of this License, and multiple
3718 identical Invariant Sections may be replaced with a single copy. If there
3719 are multiple Invariant Sections with the same name but different contents,
3720 make the title of each such section unique by adding at the end of it, in
3721 parentheses, the name of the original author or publisher of that section
3722 if known, or else a unique number. Make the same adjustment to the
3723 section titles in the list of Invariant Sections in the license notice of
3727 In the combination, you must combine any sections Entitled "History" in
3728 the various original documents, forming one section Entitled "History";
3729 likewise combine any sections Entitled "Acknowledgements", and any
3730 sections Entitled "Dedications". You must delete all sections Entitled
3733 <bridgehead id="Collections" renderas="sect1">
3734 6. COLLECTIONS OF DOCUMENTS
3737 You may make a collection consisting of the Document and other documents
3738 released under this License, and replace the individual copies of this
3739 License in the various documents with a single copy that is included in
3740 the collection, provided that you follow the rules of this License for
3741 verbatim copying of each of the documents in all other respects.
3744 You may extract a single document from such a collection, and distribute
3745 it individually under this License, provided you insert a copy of this
3746 License into the extracted document, and follow this License in all other
3747 respects regarding verbatim copying of that document.
3749 <bridgehead id="Aggregation" renderas="sect1">
3750 7. AGGREGATION WITH INDEPENDENT WORKS
3753 A compilation of the Document or its derivatives with other separate and
3754 independent documents or works, in or on a volume of a storage or
3755 distribution medium, is called an "aggregate" if the copyright resulting
3756 from the compilation is not used to limit the legal rights of the
3757 compilation's users beyond what the individual works permit. When the
3758 Document is included in an aggregate, this License does not apply to the
3759 other works in the aggregate which are not themselves derivative works of
3763 If the Cover Text requirement of section 3 is applicable to these copies
3764 of the Document, then if the Document is less than one half of the entire
3765 aggregate, the Document's Cover Texts may be placed on covers that bracket
3766 the Document within the aggregate, or the electronic equivalent of covers
3767 if the Document is in electronic form. Otherwise they must appear on
3768 printed covers that bracket the whole aggregate.
3770 <bridgehead id="Translation" renderas="sect1">
3774 Translation is considered a kind of modification, so you may distribute
3775 translations of the Document under the terms of section 4. Replacing
3776 Invariant Sections with translations requires special permission from
3777 their copyright holders, but you may include translations of some or all
3778 Invariant Sections in addition to the original versions of these Invariant
3779 Sections. You may include a translation of this License, and all the
3780 license notices in the Document, and any Warranty Disclaimers, provided
3781 that you also include the original English version of this License and the
3782 original versions of those notices and disclaimers. In case of a
3783 disagreement between the translation and the original version of this
3784 License or a notice or disclaimer, the original version will prevail.
3787 If a section in the Document is Entitled "Acknowledgements",
3788 "Dedications", or "History", the requirement (section 4) to Preserve its
3789 Title (section 1) will typically require changing the actual title.
3791 <bridgehead id="Termination" renderas="sect1">
3795 You may not copy, modify, sublicense, or distribute the Document except as
3796 expressly provided for under this License. Any other attempt to copy,
3797 modify, sublicense or distribute the Document is void, and will
3798 automatically terminate your rights under this License. However, parties
3799 who have received copies, or rights, from you under this License will not
3800 have their licenses terminated so long as such parties remain in full
3803 <bridgehead id="FutureRevisions" renderas="sect1">
3804 10. FUTURE REVISIONS OF THIS LICENSE
3807 The Free Software Foundation may publish new, revised versions of the GNU
3808 Free Documentation License from time to time. Such new versions will be
3809 similar in spirit to the present version, but may differ in detail to
3810 address new problems or concerns. See <ulink
3811 url="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</ulink>.
3814 Each version of the License is given a distinguishing version number. If
3815 the Document specifies that a particular numbered version of this License
3816 "or any later version" applies to it, you have the option of following the
3817 terms and conditions either of that specified version or of any later
3818 version that has been published (not as a draft) by the Free Software
3819 Foundation. If the Document does not specify a version number of this
3820 License, you may choose any version ever published (not as a draft) by the
3821 Free Software Foundation.
3823 <bridgehead id="HowToUse" renderas="sect1">
3824 ADDENDUM: How to use this License for your documents
3827 To use this License in a document you have written, include a copy of the
3828 License in the document and put the following copyright and license
3829 notices just after the title page:
3833 Copyright (C) YEAR YOUR NAME.
3836 Permission is granted to copy, distribute and/or modify this document
3837 under the terms of the GNU Free Documentation License, Version 1.2 or
3838 any later version published by the Free Software Foundation; with no
3839 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
3840 copy of the license is included in the section entitled "GNU Free
3841 Documentation License".
3845 If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
3846 replace the "with...Texts." line with this:
3850 with the Invariant Sections being LIST THEIR TITLES, with the
3851 Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
3855 If you have Invariant Sections without Cover Texts, or some other
3856 combination of the three, merge those two alternatives to suit the
3860 If your document contains nontrivial examples of program code, we
3861 recommend releasing these examples in parallel under your choice of free
3862 software license, such as the GNU General Public License, to permit their
3863 use in free software.
3869 <!-- Keep this comment at the end of the file
3874 sgml-namecase-general:t
3875 sgml-general-insert-case:lower
3876 sgml-minimize-attributes:nil
3877 sgml-always-quote-attributes:t
3879 sgml-indent-data:nil
3880 sgml-parent-document:nil
3881 sgml-exposed-tags:nil
3882 sgml-local-catalogs:nil
3883 sgml-local-ecat-files:nil
projects / fspm_howto / blob