-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
-
-<article>
-
-<!-- Header -->
-
- <artheader>
- <title>Free Software Development HOWTO</title>
-
- <author>
- <firstname>Benjamin</firstname>
- <othername>Mako</othername>
- <surname>Hill</surname>
- <affiliation>
- <address>
- <email>mako@debian.org</email>
- </address>
- </affiliation>
- </author>
- <revhistory>
- <revision>
- <revnumber>v0.2.1</revnumber>
- <date>10 April 2001</date>
- <authorinitials>bch</authorinitials>
- </revision>
- </revhistory>
-
- <revhistory>
- <revision>
- <revnumber>v0.2</revnumber>
- <date>8 April 2001</date>
- <authorinitials>bch</authorinitials>
- </revision>
-
- <revision>
- <revnumber>v0.01</revnumber>
- <date>27 March 2001</date>
- <authorinitials>bch</authorinitials>
- <revremark>Initial Release</revremark>
- </revision>
- </revhistory>
-
- <abstract>
- <indexterm>
- <primary>fswd</primary>
- </indexterm>
-
- <para>
- This HOWTO is designed for people with experience in programming
- and some skills in managing a software project but who are new to
- the world of free software. This document is meant to act as a
- guide to the non-technical aspects of free software development
- and was written to be a crash course in the people skills that
- aren't taught to commercial coders but that can make or break a
- free software project.
- </para>
- </abstract>
-
- </artheader>
-
-<!-- Section1: intro -->
-
- <sect1 id="intro">
- <title>Introduction</title>
-
- <indexterm>
- <primary>fswd!introduction</primary>
- </indexterm>
-
- <para>
- Skimming through freshmeat.net provides mountains of reasons for this
- HOWTO's existence--the Internet is littered with excellently
- written and useful programs that have faded away into the universe
- of free software forgottenness. This dismal scene made me ask
- myself, "Why?"
- </para>
-
- <para>
- This HOWTO tries to do a lot of thing (probably too many), but it
- can't answer that question and won't attempt it. What this HOWTO
- will attempt to do is give your Free Software project a fighting
- chance--an edge. If you write a piece of crap that no one is
- interested in, you can read this HOWTO until you can recite it in
- your sleep and your project will probably fail. Then again, you can
- write a beautiful, relevant piece of software and follow every
- instruction in this HOWTO and your software may still not make
- it. Sometimes life is like that. However, I'll go out a limb and
- say that if you write a great, relevant pieces of software and
- ignore the advise in this HOWTO, you'll probably fail <emphasis>
- more often</emphasis>.
- </para>
-
- <para>
- A lot of the information in this HOWTO is best called common
- sense. Of course, as any debate on interfaces will prove, what is
- common sense to some programmers proves totally unintuitive to
- others. After explaining bits and pieces of this HOWTO to Free
- Software developers on several occasions, I realized that writing
- this HOWTO might provide a useful resource and a forum for
- programmers to share ideas about what has and has not worked for
- them.
- </para>
-
- <para>
- As anyone involved in any of what seems like an unending parade of
- ridiculous intellectual property clashes will attest to, a little
- bit of legalese proves important.
- </para>
-
-<!-- Section2: copyright -->
-
- <sect2 id="copyright">
- <title>Copyright Information</title>
-
- <para>
- This document is copyrighted (c) 2000 Benjamin (Mako) Hill and is
- distributed under the terms of the Linux Documentation Project
- (LDP) license, stated below.
- </para>
-
- <para>
- Unless otherwise stated, Linux HOWTO documents are copyrighted by
- their respective authors. Linux HOWTO documents may be reproduced
- and distributed in whole or in part, in any medium physical or
- electronic, as long as this copyright notice is retained on all
- copies. Commercial redistribution is allowed and encouraged;
- however, the author would like to be notified of any such
- distributions.
- </para>
-
- <para>
- All translations, derivative works, or aggregate works
- incorporating any Linux HOWTO documents must be covered under this
- copyright notice. That is, you may not produce a derivative work
- from a HOWTO and impose additional restrictions on its
- distribution. Exceptions to these rules may be granted under
- certain conditions; please contact the Linux HOWTO coordinator at
- the address given below.
- </para>
-
- <para>
- In short, we wish to promote dissemination of this information
- through as many channels as possible. However, we do wish to
- retain copyright on the HOWTO documents, and would like to be
- notified of any plans to redistribute the HOWTOs.
- </para>
-
- <para>
- If you have any questions, please contact
- <email>linux-howto@metalab.unc.edu</email>
- </para>
- </sect2>
-
-<!-- Section2: disclaimer -->
-
- <sect2 id="disclaimer">
- <title>Disclaimer</title>
-
- <para>
- No liability for the contents of this documents can be accepted.
- Use the concepts, examples and other content at your own risk. As
- this is a new edition of this document, there may be errors and
- inaccuracies, that may of course be damaging to your system.
- Proceed with caution, and although this is highly unlikely, the
- author(s) do not take any responsibility for that.
- </para>
-
- <para>
- All copyrights are held by their by their respective owners, unless
- specifically noted otherwise. Use of a term in this document
- should not be regarded as affecting the validity of any trademark
- or service mark.
- </para>
-
- <para>
- Naming of particular products or brands should not be seen
- as endorsements.
- </para>
-
- <para>
- You are strongly recommended to take a backup of your system
- before major installation and backups at regular intervals.
- </para>
- </sect2>
-
-<!-- Section2: newversions-->
-
- <sect2 id="newversions">
- <title>New Versions</title>
-
- <indexterm>
- <primary>fswd!news on</primary>
- </indexterm>
-
- <para>
- This is the second pre-release of this HOWTO. It is written to be
- released to developers for critique and brainstorming and
- submitted to Hampshire College for academic credit. Please keep in
- mind that this version of the HOWTO is still in an infant stage
- and will be revised extensively before it gets publicized widely.
- </para>
-
- <para>
- The latest version number of this document should always be listed
- on <ulink url="http://people.debian.org/~mako/projects/howto">the projects
- homepage </ulink> hosted by Debian.
- </para>
-
- <para>
- The newest version of this HOWTO will always be made available at
- the same website, in a variety of formats:
- </para>
-
- <para>
- <itemizedlist>
-
- <listitem>
- <para>
- <ulink url="http://people.debian.org/~mako/projects/howto/FreeSoftwareDevelopment-HOWTO/t1.html">HTML</ulink>.
- </para>
- </listitem>
-
-
- <listitem>
- <para>
- <ulink url="http://people.debian.org/~mako/projects/howto/FreeSoftwareDevelopment-HOWTO.html">HTML (single page)</ulink>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <ulink URL="http://people.debian.org/~mako/projects/howto/FreeSoftwareDevelopment-HOWTO.txt">plain text</ulink>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <ulink url="http://people.debian.org/~mako/projects/howto/FreeSoftwareDevelopment-HOWTO.ps.gz">Compressed postscript</ulink>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <ulink url="http://people.debian.org/~mako/projects/howto/FreeSoftwareDevelopment-HOWTO.sgml.gz">Compressed SGML source</ulink>.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </sect2>
-
-<!-- Section2: credits -->
-
- <sect2 id="credits">
- <title>Credits</title>
-
- <para>
- In this version I have the pleasure of acknowledging:
- </para>
-
- <para>
- Josh Crawford, Andy King, and Jaime Davila who all read through
- this beast and gave me feedback that has helped me make changes
- and improvements to this document. I can't thank you guys enough
- for your help.
- </para>
-
- <para>
- <emphasis>Karl Fogel</emphasis>, the author of <emphasis>Open
- Source Development with CVS</emphasis> published by the Coriolis
- Open Press. Large parts of his book are available <ulink
- url="http://cvsbook.red-bean.com">on the web</ulink>. 225 pages of
- the book are available under the GPL and constitute the best
- tutorial on CVS I've ever seen. The rest of the book covers, "the
- challenges and philosophical issues inherent in running an Open
- Source project using CVS." The book does a good job of covering
- some of the subjects brought up in this HOWTO and much
- more. <ulink url="http://cvsbook.red-bean.com">The book's
- website</ulink> has information on ordering the book and provides
- several translations of the chapters on CVS. If you are seriously
- interested in running a Free Software project, you want this
- book. I tried to mention Fogel in sections of this HOWTO where I
- knew I was borrowing directly from his ideas. If I missed any, I'm
- sorry. I'll try and have those fixed in future versions.
- </para>
-
- <para>
- Karl Fogel can be reached at <email>kfogel (at) red-bean (dot)
- com</email>
- </para>
-
- <para>
- Also providing support material, and inspiration for this HOWTO is
- Eric S. Raymond for his prolific, consistent, and carefully
- crafted arguments and Lawrence Lessig for reminding me of the
- importance of Free Software. Additionaly, I want to thank every
- user and developer involved with the <ulink
- url="http://www.debian.org">Debian Project</ulink>. The project
- has provided me with a home, a place to practice free software
- advocacy, a place to make a difference, a place to learn from
- those how have been involved with the movement much longer than I,
- and proof of a free software project that definitely, definitely
- works.
- </para>
-
- <para>
- Above all, I want to thank <emphasis>Richard Stallman</emphasis>
- for his work at the Free Software Foundation and for never giving
- up. Stallman provides and articulates the philosophical basis that
- attracts me to free software and that drives me towards writing a
- document to make sure it succeeds. RMS can always be emailed at
- <email>rms (at) gnu (dot) org</email>.
- </para>
-
- </sect2>
-
-<!-- Section2: feedback -->
-
- <sect2 id="feedback">
- <title>Feedback</title>
-
- <para>
- Feedback is always and most certainly welcome for this
- document. Without your submissions and input, this document
- wouldn't exist. Do you feel that something is missing? Don't
- hesitate to contact me to have me write a chapter, section, or
- subsection or to write one yourself. I want this document to be a
- product of the Free Software development process that it heralds
- and I believe that its ultimate success will be rooted in its
- ability to do this. Please send your additions, comments, and
- criticisms to the following email address:
- <email>mako@debian.org</email>.
- </para>
- </sect2>
-
-<!-- Section2: translations -->
-
- <sect2 id="translations">
- <title>Translations</title>
-
- <para>
- I know that not everyone speaks English. Translations are nice and
- I'd love for this HOWTO to gain the kind of international reach
- afforded by translated versions.
- </para>
-
- <para>
- However, this HOWTO is still young and I have to yet to be
- contacted about a translation so English is all that is currently
- available. If you would like to help with or do a translation, you
- will gain my utmost respect and admiration and you'll get to be
- part of a cool process. If you are at all interested, please don't
- hesitate to contact me at: <email>mako@debian.org</email>.
- </para>
- </sect2>
- </sect1>
-
-<!-- Section1: intro: END -->
-
-<!-- Section1: starting -->
-
- <sect1 id="starting">
- <title>Starting a Project</title>
-
- <indexterm>
- <primary>fswd!starting</primary>
- </indexterm>
- <para>
- With very little argument, the beginning is the most difficult part
- of successful free software development. Laying a firm foundation
- will determine whether your project flourishes or withers away and
- dies. It is also the subject that is of most immediate interest to
- anyone reading this document as a tutorial.
- </para>
-
- <para>
- Starting a project involves a dilemma that you as a developer must
- try and deal with: no potential user for your program is interested
- in a program that doesn't work while the development process that
- you want to employ holds involvement of users as imperative.
- </para>
-
- <para>
- It is in these dangerous initial moments that anyone working to
- start a free software project must try and strike a balance along
- these lines. One of the most important ways that someone trying to
- start a project can work towards this balance is by establishing a
- solid framework for the development process through some of the
- suggestions mentioned in this section.
- </para>
-
-
-<!-- Section2: chooseproject-->
-
- <sect2 id="chooseproject">
- <title>Choosing a Project</title>
-
- <para>
- If you are reading this document, there's a good chance you
- already have an idea for a project in mind. Chances are also
- pretty good that it fills a percieved gap by doing something that
- no other free software project does or by doing something in a way
- that is unique enough to necessitate a brand new piece of
- software.
- </para>
-
- <sect3 id=identifyidea>
- <title>Identify and articulate your idea</title>
- <para>
- Eric S. Raymond writes about how free software projects start in
- his essay, <ulink
- url="http://www.tuxedo.org/~esr/writings/cathedral-bazaar/"><quote>The
- Cathedral and the Bazaar,</quote></ulink> which comes as required
- reading for any free software developer. It is available online .
- </para>
-
- <para>
- In <quote>The Cathedral and the Bazaar,</quote> Raymond tells us
- that: <quote>every good work of software starts by scratching
- a developers itch.</quote> Raymond's now widely accepted
- hypothesis is that new free software programs are written, first
- and foremost, to solve a specific problem facing the developer.
- </para>
-
- <para>
- If you have an idea for a program in mind, chances are good that
- it targets a specific problem or <quote>itch</quote> you want to
- see scratched. <emphasis>This idea is the project.</emphasis>
- Articulate it clearly. Write it out. Describe the problem you
- will attack in detail. The success of your project in tackling a
- particular problem will be tied to your ability to identify that
- problem clearly early on. Find out exactly what it is that you
- want your project to do.
- </para>
-
- <para>
- Monty Manley articulates the importance of this initial step in
- an essay, <quote><ulink
- url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
- Projects the Open Source Way.</ulink></quote> As the next section
- will show, there is <emphasis>a lot</emphasis> of work that needs
- to be done before software is even ready to be coded. Manley
- says, <quote>Beginning an OSS project properly means that a
- developer must, first and foremost, avoid writing code too
- soon!</quote>
- </para>
- </sect3>
-
- <sect3 id=evalulateidea>
- <title>Evaluate your idea</title>
-
- <para>
- In evaluating your idea, you need to first ask yourself a few
- questions. This should happen before you move any further
- through this HOWTO. Ask yourself: <emphasis>Is the free software
- development model really is the right one for your
- project?</emphasis>
- </para>
-
- <para>
- Obviously, since the program scratches your itch, you are
- definitely interested in seeing it implemented in code. But,
- because one hacker coding in solitude fails to qualify as a free
- software development effort, you need to ask yourself a second
- question: <emphasis>Is anybody else interested?</emphasis>
- </para>
-
- <para>
- Sometimes the answer is a simple <quote>no.</quote> If you want
- to write a set of scripts to sort <emphasis>your</emphasis>
- <acronym>MP3</acronym> collection on <emphasis>your</emphasis>
- machine, <emphasis>maybe</emphasis> the free software development
- model is not the best one to choose. However, if you want to
- write a set of scripts to sort <emphasis>anyone's</emphasis>
- <acronym>MP3</acronym>s, a free software project might fill a
- useful gap.
- </para>
-
- <para>
- Luckily, The Internet is a place so big and so diverse that,
- chances are, there is someone, somewhere, who shares your
- interests and how feels the same <quote>itch.</quote> It is the
- fact that there are so many people with so many similar needs and
- desires that introduces the third major question: <emphasis>Has
- somebody already had your idea or a reasonably similar
- one?</emphasis>
- </para>
-
- <sect4 id=evalwhere>
- <title>Finding Similar Projects</title>
-
- <para>
- There are places you can go on the web to try and answer the
- question above. If you have experience with the free software
- community, you are probably already familiar with many of these
- sites. All of the resources listed bellow offer searching of
- their databases:
- </para>
-
- <para>
- <variablelist>
- <varlistentry>
- <term>freshmeat.net</term>
- <listitem>
- <para><ulink url="http://freshmeat.net">freshmeat.net</ulink>
- describes itself as, <quote>the Web's largest index of Linux
- and Open Source software</quote> and its reputation along
- these lines is totally unparalleled and unquestioned. If you
- can't find it on freshmeat, its doubtful that you (or anyone
- else) will find it at all.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Slashdot</term>
- <listitem>
- <para><ulink url="http://slashdot.org">Slashdot</ulink>
- provides <quote>News for Nerds: Stuff that Matters,</quote>
- which usually includes discussion of free software, open
- source, technology, and geek culture new and events. It is
- not unusual for an particularly sexy development effort to be
- announced here so it definitely worth checking.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>SourceForge</term>
- <listitem>
- <para><ulink url="http://sourceforge.net">SourceForge</ulink>
- houses and facilitates a growing number of open source and
- free software projects. It is also quickly becoming a nexus
- and an necessary stop for free software
- developers. SourceForge's <ulink
- url="http://sourceforge.net/softwaremap/trove_list.php">software
- map</ulink> and <ulink url="http://sourceforge.net/new/"> new
- release</ulink> pages should be necessary stops before
- embarking on a new free software project. SourceForge also
- provides a at <ulink
- url="http://sourceforge.net/snippet/">Code Snippet
- Library</ulink> which contains useful reusable chunks of code
- in an array of languages which can come in useful in any
- project.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Google and Google's Linux Search</term>
- <listitem>
- <para><ulink url="http://www.google.com">Google</ulink> and
- <ulink url="http://www.google.com/linux"> Google's Linux
- Search</ulink>, provide powerful web searches that may reveal
- people working on similar projects. It is not a catalog of
- software or news like freshmeat or Slashdot, but it is worth
- checking to make sure you aren't pouring your effort into a
- redundant project.</para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </para>
- </sect4>
-
- <sect4 id=evalhow>
- <title>Deciding to Proceed</title>
- <para>
- Once you have successfully charted the terrain and have an idea
- about what kinds of similar free software projects exist, every
- developer needs to decide whether to proceed with their own
- project. It is rare that a new project seeks to accomplish a
- goal that is not at all similar or related to the goal of
- another project. Anyone starting a new project needs to ask
- themselves: <quote>Will the new project be duplicating work done
- by another project? Will the new project be competing for
- developers with an existing project? Can the goals of the new
- project be accomplished by adding functionality to an existing
- project?</quote>
- </para>
-
- <para>
- If the answer to any of these questions is <quote>yes,</quote>
- try to contact the developer of the existing project(s) in
- question and see if he or she might be willing to collaborate
- with you.
- </para>
-
- <para>
- For many developers this may be the single most difficult aspect
- of free software development but it is an essential one. It is
- easy to become fired up by an idea and be caught up in the
- momentum and excitement of a new project. It is often extremely
- difficult to do but, it is important that any free software
- developer remember that the best interests of the free software
- community and the quickest way to accomplish your own project's
- goals and the goals of similar projects can often be
- accomplished by <emphasis>not</emphasis> starting a new
- development effort.
- </para>
-
- </sect4>
- </sect3>
- </sect2>
-
-<!-- Section2: naming-->
-
- <sect2 id="naming">
- <title>Naming your project</title>
-
- <para>
- While there are plenty of projects that fail with descriptive
- names and plenty that succeed without them, I think naming your
- project is worth giving a bit of thought. Leslie Orchard tackles
- this issue in an <ulink
- url="http://www.advogato.org/article/67.html">Advogato
- article</ulink>. His article is short and definately worth looking
- over quickly.
- </para>
-
- <para>
- The synopsis is that Orchard recommends you pick a name where,
- after hearing the name, many users or developers will both:
- </para>
-
- <para>
- <itemizedlist>
- <listitem>
- <para>Know what the project does.</para>
- </listitem>
- <listitem>
- <para>Remember it tomorrow.</para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- Humorously, Orchard's project, <quote>Iajitsu,</quote> does
- neither. It is probably unrelated that development has effectively
- frozen since the article was written.
- </para>
-
- <para>
- He makes a good point though. There are companies whose only job
- is to make names for pieces of software. They make
- <emphasis>ridiculous</emphasis> amount of money doing it and are
- supposedly worth it. While you probably can't aford a company like
- this, you can afford to learn from their existance and think a
- little bit about the name you are giving your project because it
- <emphasis>does</emphasis> matter.
- </para>
-
- <para>
- If there is a name you really want but it doesn't fit Orchard's
- criteria, you can still go ahead. I thought <quote>gnubile</quote>
- was one of the best I'd heard for a free software project ever and
- I still talk about it long after I've stopped using the
- program. However, if you can flexible on the subject, listen to
- Orchard's advice. It might help you.
- </para>
- </sect2>
-
-<!-- Section2: licensing-->
-
- <sect2 id="licensing">
- <title>Licensing your Software</title>
-
- <para>
- On one (somewhat simplistic) level, the difference between a piece
- of free software and a piece of propriety software is the
- license. A license helps you as the developer by protecting your
- legal rights to have your software distributed under your terms
- and helps demonstrate to those who wish to help you or your
- project that they are encouraged to join.
- </para>
-
- <sect3 id="chooselicense">
- <title>Choosing a license</title>
-
- <para>
- Any discussion of licenses is also sure to generate at least a
- small flame war as there are strong feelings that some free
- software licenses are better than others. This discussion also
- brings up the question of <quote>Open Source Software</quote> and
- the debate over the terms <quote>Open Source Software</quote> and
- <quote>Free Software</quote>. However, because I've written the
- Free Software Development HOWTO and not the Open Source
- Development HOWTO, my own allegiances in this argument are in the
- open.
- </para>
-
- <para>
- In attempting to reach a middle ground through diplomacy without
- sacrificing my own philosophy, I will recommend picking any
- license that conforms to the <ulink
- url="http://www.debian.org/social_contract">Debian Free Software
- Guidelines</ulink>. Originally compiled by the Debian project
- under Bruce Perens, the <acronym>DFSG</acronym> forms the first
- version of the <ulink
- url="http://www.opensource.org/docs/definition_plain.html">Open
- Source Definition.</ulink> Examples of free licenses given by the
- <acronym>DFSG</acronym> are the <acronym>GPL</acronym>, the
- <acronym>BSD</acronym>, and the Artistic License.
- </para>
-
- <para>
- Conforming to the definition of free software offered by Richard
- Stallman in <ulink
- url="http://www.gnu.org/philosophy/free-sw.html"><quote>The Free
- Software Definition</quote></ulink>, any of these licenses will
- uphold, <quote>users' freedom to run, copy, distribute, study,
- change and improve the software.</quote> There are plenty of
- other licenses that also conform to the <acronym>DFSG</acronym>
- but sticking with a more well-known license will offer the advantage
- of immediate recognition and understanding.
- </para>
-
- <para>
- In attempting a more in-depth analysis, I agree with Karl Fogel's
- description of licenses as falling into two groups: those that
- are the <acronym>GPL</acronym> and those that are not the
- <acronym>GPL</acronym>.
- </para>
-
- <para>
- Personally, I license all my software under the
- <acronym>GPL</acronym>. Created and protected by the Free
- Software Foundation and the GNU Project, the
- <acronym>GPL</acronym> is the license for the Linux kernel,
- GNOME, Emacs, and the vast majority of GNU/Linux software. It's
- the obvious choice but I believe it is a good one. Any BSD
- fanatic will urge you to remember that there is a viral aspect to
- the <acronym>GPL</acronym> that prevents the mixture of
- <acronym>GPL</acronym>'ed code with non-<acronym>GPL</acronym>'ed
- code. To many people (myself included), this is a benefit, but to
- some, it is a major drawback.
- </para>
-
- <para>
- The three major licenses can be found at the following locations:
- </para>
-
- <para>
- <itemizedlist>
- <listitem>
- <para><ulink url="http://www.gnu.org/copyleft/gpl.html">The GNU
- General Public License</ulink></para>
- </listitem>
- <listitem>
- <para><ulink url="http://www.debian.org/misc/bsd.license">The
- BSD License</ulink></para>
- </listitem>
- <listitem>
- <para><ulink
- url="http://language.perl.com/misc/Artistic.html">The Artistic
- License</ulink></para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- <emphasis>In any case, please read through any license before
- your release your software under it. As the primary developer,
- you can't afford any license surprises.</emphasis>
- </para>
- </sect3>
-
- <sect3 id="licensechoose">
- <title>The mechanics of licensing</title>
-
- <para>
- The text of the <acronym>GPL</acronym> offers <ulink
- url="http://www.gnu.org/copyleft/gpl.html#SEC4">a good
- description of the mechanics of applying a license</ulink> to a
- piece of software. My quick checklist for applying a license
- includes:
- </para>
-
- <para>
- <itemizedlist>
-
- <listitem>
- <para>If at all possible, attach and distribute a full copy of
- the license with the source and binary by including a separate
- file.</para>
- </listitem>
-
- <listitem>
- <para>At the top of each source file in your program, attach a
- notice of copyright and include information on where the full
- license can be found. The <acronym>GPL</acronym> recommends
- that each file begin with:</para>
-
- <screen>
-<emphasis>one line to give the program's name and an idea of what it does.</emphasis>
-Copyright (C) yyyy name of author
-
-This program is free software; you can redistribute it and/or
-modify it under the terms of the GNU General Public License
-as published by the Free Software Foundation; either version 2
-of the License, or (at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with this program; if not, write to the Free Software
-Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
- </screen>
-
- <para>
- The <acronym>GPL</acronym> goes on to recommend attaching
- information on methods for contacting you (the author) via
- email or physical mail.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The <acronym>GPL</acronym> continues and suggests that if your
- program runs in an interactive mode, you should write the
- program to output a notice each time it enters interactive
- mode that includes a message like this one that points to full
- information about the programs license:
- </para>
-
- <screen>
-Gnomovision version 69, Copyright (C) year name of author
-Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
-type `show w'. This is free software, and you are welcome
-to redistribute it under certain conditions; type `show c'
-for details.
- </screen>
- </listitem>
-
- <listitem>
- <para>Finally, it might be helpful to include a
- <quote>copyright disclaimer</quote> from an employer or a
- school if you work as a programmer or if it seems like your
- employer or school might be able to make an argument for
- ownership of your code later on. These aren't often needed but
- there are plenty of free software developers who have gotten
- into trouble and wish they'd asked for one.</para>
- </listitem>
-
- </itemizedlist>
- </para>
- </sect3>
-
- <sect3 id="licensewarning">
- <title>Final license warning</title>
-
- <para>
- Please, please, please, place your software under
- <emphasis>some</emphasis> license. It may not seem important, and
- to you it may not be, but licenses <emphasis>are</emphasis>
- important. For a piece of software to be included in the Debian
- GNU/Linux distribution, it must have a license that fits the
- <ulink url="http://www.debian.org/social_contract">Debian Free
- Software Guidelines</ulink>. If your software has no license, it
- can not be distributed as a package in Debian until you
- re-release it under a free license. Please save yourself and
- others trouble by releasing the first version of your software
- with a clear license.
- </para>
-
- </sect3>
-
- </sect2>
-
-<!-- Section2: chooseversioning-->
-
- <sect2 id="chooseversioning">
- <title>Choosing a Method of Version Numbering</title>
-
- <para>
- <emphasis>The most important thing about a system of version
- numbering is that there is one.</emphasis> It may seem pedantic to
- emphasize this point but you'd be surprised at the number of
- scripts and small programs that pop up without any version number
- at all.
- </para>
-
- <para>
- <emphasis>The second most important thing about a system of
- numbering is that the numbers always go up.</emphasis> Automatic
- version tracking systems and people's sense of order in the
- universe will fall apart if version numbers don't rise. It doesn't
- <emphasis>really</emphasis> matter if 2.1 is a big jump and
- 2.0.005 is a small jump but it does matter that 2.1 is more recent
- than 2.0.005.
- </para>
-
- <para>
- Follow these two simple rules and you will not go (too)
- wrong. Beyond this, the most common technique seems to be the
- <quote>major level,</quote> <quote>minor level,</quote>
- <quote>patch level</quote> version numbering scheme. Whether you
- are familiar with the name or not, you interact with it all the
- time. The first number is the major number and it signifies major
- changes or rewrites. The second number is the minor number and it
- represents added or tweaked functionality on top of a largely
- coherant structure. The third number is the patch number and it
- usually will only refer to releases fixing bugs.
- </para>
-
- <para>
- The widespread use of this scheme is why I know the nature and
- relative degree in the differences between a 2.4.12 release of the
- Linux kernel and a 2.4.11, 2.2.12, and 1.2.12 without knowning
- anything about any of the releases.
- </para>
-
- <para>
- You can bend or break these rules, and people do. But beware, if
- you choose to, someone will get annoyed, assume you don't know,
- and try and educate you, probably not nicely. I always follow this
- method and I implore you to do so as well.
- </para>
-
- <para>
- There are several version numbering systems that are well known,
- useful, and that might be worth looking into before you release
- your first version.
- </para>
-
- <variablelist>
- <varlistentry>
- <term>Linux kernel version numbering:</term>
- <listitem>
- <para>The Linux kernel uses a versioning system where any odd
- minor version number refers to an development or testing release
- and any even minor version number refers to a stable
- version. Think about it for a second. Under this system, 2.1 and
- 2.3 kernels were and always will be development or testing
- kernels and 2.0, 2.2. and 2.4 kernels are all production code
- with a higher degree of stability and more testing.
- </para>
-
- <para>
- Whether you plan on having a split development model (as
- described in <xref linkend="branches">) or only one version
- released at a time, my experience with several free software
- projects and with the Debian project has taught me that use of
- Linux's version numbering system is worth taking into
- consideration. In Debian, <emphasis>all</emphasis> minor
- versions are stable distributions (2.0, 2.1, etc). However,
- many people assume that 2.1 is an unstable or development
- version and continue to use an older version until they get so
- frustrated with the lack of development progress that they
- complain and figure the system out. If you never release an odd
- minor version but only release even ones, nobody is hurt, and
- less people are confused. It's an idea worth taking into
- consideration.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Wine version numbering:</term>
- <listitem>
- <para>Because of the unusual nature of wine's development where
- the not-emulator is constantly improving but not working towards
- any immediately achievable goal, wine is released every three
- weeks. Wine does this by labeling their releases in <quote>Year
- Month Day</quote> format where each release might be labeled
- <quote>wine-XXXXXXXX</quote> where the version from January 04,
- 2000 would be <quote>wine-20000104</quote>. For certain
- projects, <quote>Year Month Day</quote> format can make a lot of
- sense.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Mozilla milestones:</term>
- <listitem>
- <para>When one considers Netscape 6 and vendor versions, the
- mozilla's project development structure is one of the most
- complex free software models available. The project's version
- numbering has reflected the unique situation in which it is
- developed.
- </para>
-
- <para>
- Mozilla's version numbering structure has historically been
- made up of milestones. From the beginning of the mozilla
- project, the goals of the project in the order and degree to
- which they were to be achieved were charted out on a series of
- <ulink url="http://www.mozilla.org/roadmap.html">road
- maps</ulink>. Major points and achievements along these
- road-maps were marked as milestones. Therefore, although
- mozilla was built and distributed nightly as <quote>nightly
- builds,</quote> on a day when the goals of a milestone on the
- road-map had been reached, that particular build was marked as
- a <quote>milestone release.</quote>
- </para>
-
- <para>
- While I haven't seen this method employed in any other projects
- to date, I like the idea and think that it might have value in
- any testing or development branch of a large application under
- heavy development.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect2>
-
-<!-- Section2: documentation-->
-
- <sect2 id="documentation">
- <title>Documentation</title>
-
- <para>
- A huge number of otherwise fantastic free software applications
- have withered and died because their author was the only person
- who knew how to use them fully. Even if your program is written
- primarily for a techno-savvy group of users, documentation is
- helpful and even necessary for the survival of your project. You
- will learn later in <xref linkend="releasing"> that you should
- always release something that is usable. <emphasis>A piece of
- software without documentation is not usable.</emphasis>
- </para>
-
- <para>
- There are lots of different people you should document for and
- there are lots of ways to document your project. <emphasis>The
- importance of documentation in source code to help facilitate
- development by a large community is vital</emphasis> but it falls
- outside the scope of this HOWTO. This being the case, this section
- deals with useful tactics for user-directed documentation.
- </para>
-
- <para>
- A combination of tradition and necessity has resulted in a
- semi-regular system of documentation in most free software
- projects that is worth following. Both users and developers expect
- to be able to get documentation in several ways and it's essential
- that you provide the information they are seeking in a form they
- can read if your project is ever going to get off the
- ground. People have come to expect:
- </para>
-
- <sect3>
- <title>Man pages</title>
-
- <para>Your users will want to be able to type <quote>man
- yourprojectname</quote> end up with a nicely formatted man page
- highlighting the basic use of your application. Make sure that
- before you release your program, you've planned for this.
- </para>
-
- <para>
- Man pages are not difficult to write. There is excellent
- documentation on the man page writing process available through
- the <quote>The Linux Man-Page-HOWTO</quote> which is available
- through the Linux Documentation project <acronym>(LDP)</acronym>
- and is written by Jens Schweikhardt. It is available <ulink
- url="http://www.schweikhardt.net/man_page_howto.html">from
- Schweikhardt's site</ulink> or <ulink
- url="http://www.linuxdoc.org/HOWTO/mini/Man-Page.html">from the
- <acronym>LDP</acronym></ulink>.
- </para>
-
- <para>
- It is also possible to write man pages using DocBook
- SGML. Because man pages are so simple and the DocBook method
- relatively new, I have not been able to follow this up but would
- love help from anyone who can give me more information on how
- exactly how this is done.
- </para>
- </sect3>
-
- <sect3>
- <title>Command line accessible documentation</title>
-
- <para>
- Most users will expect some basic amount of documentation to be
- easily available from the command line. For few programs should
- this type of documentation extend for more than one screen (24 or
- 25 lines) but it should cover the basic usage, a brief (one or
- two sentence) description of the program, a list of the commands
- with explanations, as well as all the major options (also with
- explanations), plus a pointer to more in-depth documentation for
- those who need it. The command line documentation for Debian's
- apt-get serves as an excellent example and a useful model:
- </para>
-
- <screen>
-apt 0.3.19 for i386 compiled on May 12 2000 21:17:27
-Usage: apt-get [options] command
- apt-get [options] install pkg1 [pkg2 ...]
-
-apt-get is a simple command line interface for downloading and
-installing packages. The most frequently used commands are update
-and install.
-
-Commands:
- update - Retrieve new lists of packages
- upgrade - Perform an upgrade
- install - Install new packages (pkg is libc6 not libc6.deb)
- remove - Remove packages
- source - Download source archives
- dist-upgrade - Distribution upgrade, see apt-get(8)
- dselect-upgrade - Follow dselect selections
- clean - Erase downloaded archive files
- autoclean - Erase old downloaded archive files
- check - Verify that there are no broken dependencies
-
-Options:
- -h This help text.
- -q Loggable output - no progress indicator
- -qq No output except for errors
- -d Download only - do NOT install or unpack archives
- -s No-act. Perform ordering simulation
- -y Assume Yes to all queries and do not prompt
- -f Attempt to continue if the integrity check fails
- -m Attempt to continue if archives are unlocatable
- -u Show a list of upgraded packages as well
- -b Build the source package after fetching it
- -c=? Read this configuration file
- -o=? Set an arbitary configuration option, eg -o dir::cache=/tmp
-See the apt-get(8), sources.list(5) and apt.conf(5) manual
-pages for more information and options.
- </screen>
-
- <para>
- It has become a GNU convention to make this type of information
- accessible with the <quote>-h</quote> and the
- <quote>--help</quote> options. Most GNU/Linux users will expect
- to be able to retrieve basic documentation these ways so if you
- choose to use different methods, be prepared for the flames and
- fallout that may result.
- </para>
- </sect3>
-
- <sect3>
- <title>Files users will expect</title>
- <para>
- In addition to man pages and command-line help, there are certain
- files where people will look for documentation, especially in any
- package containing source code. In a source distribution, most of
- these files can be stored in a the root directory of the source
- distribution or in a subdirectory of the root called
- <quote>doc</quote> or <quote>Documentation.</quote> Common files
- in these places include:
- </para>
-
- <para>
- <variablelist>
- <varlistentry>
- <term>README or Readme</term>
-
- <listitem>
- <para>A document containing all the basic installation,
- compilation, and even basic use instructions that make up the
- bare minimum information needed to get the program up and
- running. A README is not your chance to be verbose but should
- be concise and effective. An ideal README is at least 30 lines
- long and more no more than 250.</para>
- </listitem>
-
- </varlistentry>
- <varlistentry>
- <term>INSTALL or Install</term>
-
- <listitem>
- <para>The INSTALL file should be much shorter than the README
- file and should quickly and concisely describe how to build
- and install the program. Usually an INSTALL file simply
- instructs the user to run <quote>./configure; make; make
- install</quote> and touches on any unusual options or actions
- that may be necessary. For most relatively standard install
- procedures and for most programs, INSTALL files are as short
- as possible are rarely over 100 lines.</para>
- </listitem>
-
- </varlistentry>
- <varlistentry>
- <term>CHANGELOG, Changelog, ChangeLog, or changelog</term>
-
- <listitem>
- <para>A CHANGELOG is a simple file that every well-managed
- free software project should include. A CHANGELOG is simple
- the file that, as its name implies, logs or documents the
- changes you make to your program. The most simple way to
- maintain a CHANGELOG is to simply keep a file with the source
- code for your program and add a section to the top of the
- CHANGELOG with each release describing what has been, changed,
- fixed, or added to the program. It's a good idea to post the
- CHANGELOG onto the website as well because it can help people
- decide whether they want or need to upgrade to a newer version
- or wait for a more significant improvement.</para>
- </listitem>
-
- </varlistentry>
- <varlistentry>
- <term>NEWS</term>
-
- <listitem>
- <para>A NEWS file and a ChangeLog are similar. Unlike a
- CHANGELOG, a NEWS file is not typically updated with new
- versions. Whenever new features are added, the developer
- responisble will make a note in the NEWS file. NEWS files
- should not have to be changed before a release (they should be
- kept up to date all along) but it's usually a good idea to
- check first anyway because often developers just forget to
- keep them as current as they should.</para>
- </listitem>
-
- </varlistentry>
- <varlistentry>
- <term><acronym>FAQ</acronym></term>
-
- <listitem>
- <para>For those of you that don't already know,
- <acronym>FAQ</acronym> stands for Frequently Asked Questions
- and a FAQ is a collection of exactly that. FAQs are not
- difficult to make. Simply make a policy that if you are asked
- a question or see a question on a mailing list two or more
- times, add the question (and its answer) to your FAQ. FAQs are
- more optional than the files listed above but they can save
- your time, increase usability, and decrease headaches on all
- sides.</para>
- </listitem>
-
- </varlistentry>
- </variablelist>
- </para>
- </sect3>
-
- <sect3>
- <title>Website</title>
- <para>
- It's only indirectly an issue of documentation but a good website
- is quickly becoming an essential part of any free software
- project. Your website should provide access to your documentation
- (in <acronym>HTML</acronym> if possible). It should also include
- a section for news and events around your program and a section
- that details the process of getting involved with development or
- testing and make an open invitation. It should also supply links
- to any mailing lists, similar websites, and provide a direct link
- to all the available ways of downloading your software.
- </para>
- </sect3>
-
- <sect3>
- <title>Other documentation hints</title>
-
- <para>
- All your documentation should be in plaintext, or, in cases where
- it is on your website primarily, in HTML. Everyone can cat a
- file, everyone has a pager, (almost) everyone can render
- HTML. <emphasis>You are welcome to distribute information in PDF,
- PostScript, RTF, or any number of other widely used formats but
- this information must also be available in plaintext or HTML or
- people will be very angry at you.</emphasis>
- </para>
-
- <para>
- It doesn't hurt to distribute any documentation for your program
- from your website (FAQs etc) with your program. Don't hesitate
- throw any of this in the program's tarball. If people don't need
- it, they will delete it. I can repeat it over and over:
- <emphasis>Too much documentation is not a sin.</emphasis>
- </para>
- </sect3>
- </sect2>
-
-<!-- Section2: presentation -->
-
- <sect2 id="presentation">
- <title>Other Presentation Issues</title>
- <para>
- Many of the remaining issues surrounding the creation of a new
- free software program fall under what most people describe as
- common sense issues. Its often said that software engineering is
- 90 percent common sense combined with 10 percent specialized
- knowledge. Still, they are worth noting briefly in hopes that they
- may remind a developer of something they may have forgotten.
- </para>
-
- <sect3>
- <title>Package formats</title>
- <para>
- Package formats may differ depending on the system you are
- developing for. For windows based software, Zip archives (.zip)
- usually serve as the package format of choice. If you are
- developing for GNU/Linux, *BSD, or any UN*X, make sure that your
- source code is always available in tar'ed and gzip'ed format
- (.tar.gz). UNIX compress (.Z) has gone out of style and
- usefulness and faster computers have brought bzip2 (.bz2) into
- the spot-light as a more effective compression medium. I now make
- all my releases available in both gzip'ed and bzip2'ed tarballs.
- </para>
-
- <para>
- Binary packages should always be distribution specific. If you
- can build binary packages against a current version of a major
- distribution, you will only make your users happy. Try to foster
- relationships with users or developers of large distributiosn to
- develop a system for the consistent creation of binary
- packages. It's often a good idea to provide RedHat
- <acronym>RPM</acronym>'s (.rpm), Debian deb's (.deb) and source
- <acronym>RPM</acronym>'s <acronym>SRPM</acronym>'s if
- possible. Remember: <emphasis>While these binaries packages are
- nice, getting the source packaged and released should always be
- your priority. Your users or fellow developers can and will do
- the the binary packages for you.</emphasis>
- </para>
- </sect3>
-
- <sect3>
- <title>Version control systems</title>
-
- <para>
- A version control system can make a lot of these problems of
- packaging (and a lot of other problems mentioned in this HOWTO)
- less problematic. If you are using *NIX, CVS is your best bet. I
- recommend Karl Fogel's book on the subject (and the <ulink
- url="http://cvsbook.red-bean.com/">posted HTML version</ulink>)
- wholeheartedly.
- </para>
-
- <para>
- CVS or not, you should probably invest some time into learning
- about a version control system because it provides an automated
- way of solving many of the problems described by this HOWTO. I
- am not aware of any free version control systems for Windows or
- MacOS but I know that CVS clients exist for both
- platforms. Websites like <ulink
- url="http://sourceforge.net">SourceForge</ulink> do a great job
- as well with a nice, easy-to-use web interface to CVS.
- </para>
-
- <para>
- I'd love to devote more space in this HOWTO to CVS because I love
- it (I even use CVS to keep versions straight on this HOWTO!) but
- I think it falls outside the scope of this document and should
- (already has) its own HOWTO.
- </para>
-
- </sect3>
-
- <sect3>
- <title>Useful tidbits and presentation hints</title>
-
- <para>
- Other useful hints include:
- </para>
-
- <para>
- <itemizedlist>
-
- <listitem>
- <para>
- <emphasis>Make sure that your program can always be found in a
- single location.</emphasis> Often this means that you have a
- single directory accessible via <acronym>FTP</acronym> or the
- web where the newest version can be quickly recognized. One
- effective technique is a provide a symlink called
- <quote>yourprojectname-latest</quote> that is always pointing
- to the most recent released or development version of your
- free software application. Keep in mind that this location
- will recieve many requests for downloads around releases so
- make sure that the server you choose has adequate bandwidth.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis>Make sure that there is a consistent email address
- for bug reports.</emphasis> It's usually a good idea to make
- this something that is NOT your primary email address like
- yourprojectname@host or yourprojectname-bugs@host. This way,
- if you ever decide to hand over maintainership or if your
- email address changes, you simply need to change where this
- email address forwards. It also will allow for more than one
- person to deal with the influx of mail that is created if your
- project becomes as huge as you hope it will.
- </para>
- </listitem>
-
- </itemizedlist>
- </para>
- </sect3>
- </sect2>
- </sect1>
-
-<!-- Section1: starting: END -->
-
-<!-- Section1: developers -->
-
- <sect1 id="developers">
- <title>Maintaining a Project: Interacting with Developers</title>
- <indexterm>
- <primary>fswd!developers</primary>
- </indexterm>
-
- <para>
- Once you have gotten your project started, you have overcome the
- most difficult hurdles in the development process of your
- program. Laying a firm foundation is essential, but the development
- process itself is equally important and provides just as many
- opportunities for failure. In the next two sections, I will
- describe running a project by discussing how to maintain a
- development effort through interactions with developers and with
- users.
- </para>
-
- <para>
- In releasing your program, your program becomes free software. This
- transition is more than just a larger user base. By releasing your
- program as free software, <emphasis>your</emphasis> software
- becomes the <emphasis>free software community's</emphasis>
- software. The direction of your software's development will be
- reshaped, redirected, and fully determined by your users and, to a
- larger extent, by other developers in the community.
- </para>
-
- <para>
- The major difference between free software development and
- propriety software development is the developer base. As the leader
- of a free software project, you need to attract and keep developers
- in a way that leaders of proprietary software projects simply don't
- have to worry about. <emphasis>As the person leading development of
- a free software project, you must harness the work of fellow
- developers by making responsible decisions and by responsibly
- choosing not to make decisions. You have to direct developers
- without being overbearing or bossy. You need to strive to earn
- respect and never forget to give it out.</emphasis>
- </para>
-
-<!-- Section2: delegation -->
-
- <sect2 id="delegation">
- <title>Delegating Work</title>
-
- <para>
- By now, you've hypothetically followed me through the early
- programming of a piece of software, the creation of a website and
- system of documentation, and we've gone ahead and (as will be
- discussed in <xref linkend="releasing">) released it to the rest
- of the world. Times passes, and if things go well, people become
- interested and want to help. The patches begin flowing in.
- </para>
-
- <para>
- <emphasis>Like the parent of any child who grows up, it's now time
- to wince, smile and do most difficult thing in any parents
- life: It's time to let go.</emphasis>
- </para>
-
- <para>
- Delegation is the political way of describing this process of
- <quote>letting go.</quote> It is the process of handing some of
- the responsibility and power over your project to other
- responsible and involved developers. It is difficult for anyone
- who has invested a large deal of time and energy into a project
- but it essential for the growth of any free software project. One
- person can only do so much. A free software project is nothing
- without the involvement of <emphasis>a group</emphasis> of
- developers. A group of developers can only be maintained through
- respectful and responsible leadership and delegation.
- </para>
-
- <para>
- As your project progresses, you will notice people who are putting
- significant amounts of time and effort into your project. These
- will be the people submitting the most patches, posting most on
- the mailing lists, and engaging in long email discussions. It is
- your responsibility to contact these people and to try and shift
- some of the power and responsibility of your position as the
- project's maintainer onto them (if they want it). There are
- several easy ways you can do this:
- </para>
-
- <para>
- In a bit of a disclaimer, delegation need not mean rule by
- comittee. In many cases it does and this has been proven to
- work. In other cases this has created problems. <ulink
- url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
- Projects the Open Source Way</ulink> argues that <quote>OSS
- projects do best when one person is the clear leader of a team and
- makes the big decisions (design changes, release dates, and so
- on).</quote> I think this often true but would urge developers to
- consider the ideas that the project leader need not be the
- project's founder and that these important powers need not all rest
- with one person but that a release manager may be different than a
- lead developer. These situations are tricky politically so
- be careful and make sure it's necessary before you go around
- empowering people.
- </para>
-
- <sect3>
- <title>How to delegate</title>
-
- <para>
- You may find that other developers seem even more experienced or
- knowledgeable than you. Your job as a maintainer does not mean
- you have to be the best or the brightest. It means you
- are responsible for showing good judgment and for
- recognizing which solutions are maintainable and which are not.
- </para>
- <para>
- Like anything, its easier to watch others delegate than to do it
- yourself. In a sentence: <emphasis>Keep an eye out for other
- qualified developers who show an interest and sustained
- involvement with your project and try and shift responsibility
- towards them.</emphasis> The following ideas might be good places
- to start or good sources of inspiration:
- </para>
-
- <sect4>
- <title>Allow a larger group of people to have write access to your CVS
- repository and make real efforts towards rule by a
- committee</title>
-
- <para>
- <ulink url="http://httpd.apache.org/">Apache</ulink> is an
- example of a project that is run by small group of developers
- who vote on major technical issues and the admission of new
- members and all have write access to the main source
- repository. Their process is detailed <ulink
- url="http://httpd.apache.org/ABOUT_APACHE.html">online.</ulink>
- </para>
-
- <para>
- The <ulink url="http://www.debian.org/"> Debian Project</ulink>
- is an extreme example of rule by committee. At current count,
- more than 700 developers have full responsibility for
- aspects of the project. All these developers can upload into
- the main FTP server, and vote on major issues. Direction for
- the project is determined by the project's <ulink
- url="http://www.debian.org/social_contract">social
- contract</ulink> and a <ulink
- url="http://www.debian.org/devel/constitution">constitution</ulink>. To
- facilitate this system, there are special teams (i.e. the
- install team, the Japanese language team) as well as a technical
- committee and a project leader. The leader's main responsibility
- is to, <quote>appoint delegates or delegate decisions to the
- Technical Committee.</quote>
- </para>
-
- <para>
- While both of these projects operate on a scale that your
- project will not (at least initially), their example is
- helpful. Debian's idea of a project leader who can do
- <emphasis>nothing</emphasis> but delegate serves as a
- caricature of how a project can involve and empower a huge
- number of developers and grow to a huge size.
- </para>
-
- </sect4>
-
- <sect4 id="releasemanager">
- <title>Publicly appoint someone as the release manager for a
- specific release</title>
-
- <para>
- A release manager is usually responsible for coordinating
- testing, enforcing a code freeze, being responsible for
- stability and quality control, packaging up the software, and
- placing it in the appropriate places to be downloaded.
- </para>
-
- <para>
- This use of the release manager is a good way to give yourself a
- break and to shift the responsibility for accepting and
- rejecting patches onto someone else. It is a good way of very
- clearly defining a chunk of work on the project as belonging to
- a certain person and its a great way of giving yourself room to
- breath.
- </para>
- </sect4>
-
- <sect4 id="delegatebranch">
- <title>Delegate control of an entire branch</title>
- <para>
- If your project chooses to have branches (as described in <xref
- linkend="branches">), it might be a good idea to appoint someone
- else to be the the head of a branch. If you like focusing your
- energy on development releases and the implementation of new
- features, hand total control over the stable releases to a
- well-suited developer.
- </para>
-
- <para>
- The author of Linux, Linus Torvalds, came out and crowned Alan
- Cox as <quote>the man for stable kernels.</quote> All patches
- for stable kernels go to Alan and, if Linus were to be taken
- away from work on Linux for any reason, Alan Cox would be more
- than suited to fill his role as the acknowledged heir to the
- Linux maintainership.
- </para>
- </sect4>
- </sect3>
- </sect2>
-
-<!-- Section2: patching -->
-
- <sect2 id="patching">
- <title>Accepting and Rejecting Patches</title>
- <para>
- This HOWTO has already touched on the fact that as the maintainer
- of a free software project, one of your primary and most important
- responsibilities will be accepting and rejecting patches submitted
- to you by other developers.
- </para>
-
- <sect3>
- <title>Technical judgment</title>
-
- <para>
- In <emphasis>Open Source Development with CVS</emphasis>, Karl
- Fogel makes a convincing argument that the most important things
- to keep in mind when rejecting or accepting patches are:
- </para>
-
- <para>
- <itemizedlist>
-
- <listitem>
- <para>A firm knowledge of the scope of your program (that's the
- <quote>idea</quote> I talked about in <xref linkend="chooseproject">);</para>
- </listitem>
-
- <listitem>
- <para>The ability to recognize, facilitate, and direct
- <quote>evolution</quote> of your program so that the program
- can grow and change and incorporate functionality that was
- originally unforeseen;</para>
- </listitem>
-
- <listitem>
- <para>The necessity to avoid digressions that might expand the
- scope of the program too much and result and push the project
- towards an early death under its own weight and
- unwieldiness.</para>
- </listitem>
-
- </itemizedlist>
- </para>
-
- <para>
- These are the criteria that you as a project maintainer should
- take into account each time you receive a patch.
- </para>
-
- <para>
- Fogel elaborates on this and states the <quote>the
- questions to ask yourself when considering whether to implement
- (or approve) a change are:</quote>
- </para>
-
- <para>
- <itemizedlist>
-
- <listitem>
- <para>Will it benefit a significant percentage of the program's
- user community?</para>
- </listitem>
-
- <listitem>
- <para>Does it fit within the program's domain or within a
- natural, intuitive extension of that domain?</para>
- </listitem>
-
- </itemizedlist>
- </para>
-
- <para>
- The answers to these questions are never straightforward and its
- very possible (and even likely) that the person who submitted the
- patch may feel differently about the answer to these questions
- than you do. However, if you feel that that the answer to either
- of those questions is <quote>no,</quote> it is your responsibility
- to reject the change. If you fail to do this, the project will
- become unwieldy and unmaintainable and many ultimately fail.
- </para>
- </sect3>
-
- <sect3>
- <title>Rejecting patches</title>
-
- <para>
- Rejecting patches is probably the most difficult and sensitive
- job that the maintainer of any free software project has to
- face. But sometimes it has to be done. I mentioned earlier (in
- <xref linkend="developers"> and in <xref linkend="delegation">)
- that you need to try and balance your responsibility and power to
- make what you think are the best technical decisions with the
- fact that you will lose support from other developers if you seem
- like you are on a power trip or being overly bossy or possessive
- of the community's project. I recommend that you keep these three
- major concepts in mind when rejecting patches (or other changes):
- </para>
-
- <sect4>
- <title>Bring it to the community</title>
- <para>
- One of the best ways of justifying a decision to reject a patch
- and working to not seem like you keep an iron grip on your
- project is by not making the decision alone at all. It might
- make sense to turn over larger proposed changes or more
- difficult decisions to a development mailing list where they can
- be discussed and debated. There will be some patches (bug fixes,
- etc.) which will definitely be accepted and some that you feel
- are so offbase that they do not even merit further
- discussion. It is those that fall into the grey area between
- these two groups that might merit a quick forward to a mailing
- list.
- </para>
-
- <para>
- I recommend this process wholeheartedly. As the project
- maintainer you are worried about making the best decision for
- the project, for the project's users and developers, and for
- yourself as a responsible project leader. Turning things over to
- an email list will demonstrate your own responsibility and
- responsive leadership as it tests and serves the interests of
- your software's community.
- </para>
- </sect4>
-
- <sect4>
- <title>Technical issues are not always good justification</title>
- <para>
- Especially towards the beginning of your project's life, you
- will find that many changes are difficult to implement,
- introduce new bugs, or have other technical problems. Try to see
- past these. Especially with added functionality, good ideas do
- not always come from good programmers. Technical merit is a
- valid reason to postpone an application of a patch but it is not
- always a good reason to reject a change outright. Even small
- changes are worth the effort of working with the developer
- submitting the patch to iron out bugs and incorporate the change
- if you think it seems like a good addition to your project. The
- effort on your part will work to make your project a community
- project and it will pull a new or less experienced developer
- into your project and even teach them something that might help
- them in making their next patch.
- </para>
- </sect4>
-
- <sect4>
- <title>Common courtesy</title>
- <para>
- It should go without saying but, <emphasis>above all and in all
- cases, just be nice.</emphasis> If someone has an idea and cares
- about it enough to write some code and submit a patch, they
- care, they are motivated, and they are already involved. Your
- goal as the maintainer is make sure they submit again. They may
- have thrown you a dud this time but next time may be the idea or
- feature that revolutionizes your project.
- </para>
-
- <para>
- It is your responsibility to first justify your choice to not
- incorporate their change clearly and concisely. Then thank
- them. Let them know that you a appreciate their help and feel
- horrible that you can't incorporate their change. Let them know
- that you look forward to their staying involved and you hope
- that the next patch or idea meshes better with your project
- because you appreciate their work and want to see it in your
- application. If you have ever had a patch rejected after putting
- a large deal of time, thought, and energy into it, you remember
- how it feels and it feels bad. Keep this in mind when you have
- to let someone down. It's never easy but you need to do
- everything you can to make it as not-unpleasant as possible.
- </para>
- </sect4>
- </sect3>
- </sect2>
-
-<!-- Section2: branches -->
-
- <sect2 id="branches">
- <title>Stable and Development Branches</title>
-
- <para>
- The idea of stable and development branches has already been
- described briefly in <xref linkend="chooseversioning"> and in
- <xref linkend="delegatebranch">. These allusions attest to some of
- the ways that multiple branches can affect your software. Branches
- can let you avoid (to some extent) some of the problems around
- rejecting patches (as described in <xref linkend="patching">) by
- allowing you to temporarily compromise the stability of your
- project without affecting those users who need that stability.
- </para>
-
- <para>
- The most common way of branching your project is to have one
- branch that is stable and one that is for development. This is the
- model followed by the Linux kernel that is described in <xref
- linkend="chooseversioning">. In this model, there is
- <emphasis>always</emphasis> one branch that is stable and always
- one that is in development. Before any new release, the
- development branch goes into a <quote>feature freeze</quote> as
- described in <xref linkend="freezing"> where major changes and
- added features are rejected or put on hold under the development
- kernel is released as the new stable branch and major development
- resumes on the development branch. Bug fixes and small changes
- that are unlikely to have any large negative repercussions are
- incorporated into the stable branch as well as the development
- branch.
- </para>
-
- <para>
- Linux's model provides an extreme example. On many projects, there is no
- need to have two versions constantly available. It may make sense to
- have two versions only near a release. The Debian project has
- historically made both a stable and an unstable distribution
- available but has expanded to this to include: stable, unstable,
- testing, experimental, and (around release time) a frozen
- distribution that only incorporates bug fixes during the
- transition from unstable to stable. There are few projects whose
- size would necessitate a system like Debian's but this use of
- branches helps demonstrate how they can be used to balance
- consistent and effective development with the need to make regular
- and usable releases.
- </para>
-
- <para>
- In trying to set up a development tree for yourself, there are
- several things that might be useful to keep in mind:
- </para>
-
- <para>
- <variablelist>
-
- <varlistentry>
- <term>Minimize the number of branches</term>
- <listitem>
- <para>Debian may be able to make good use of four or five
- branches but it contains gigabytes of software in over 5000
- packages compiled for 5-6 different architectures. For you,
- two is probably a good ceiling. Too many branches will confuse
- your users (I can't count how many times I had to describe
- Debian's system when it only had 2 and sometimes 3 branches!),
- potential developers and even yourself. Branches can help but
- they come at a cost so use them very sparingly.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Make sure that all your different branches are explained</term>
- <listitem>
- <para>As I mentioned in the preceding paragraph, different
- branches <emphasis>will</emphasis> confuse your users. Do
- everything you can to avoid this by clearly explaining the
- different branches in a prominent page on your website and in a
- README file in the <acronym>FTP</acronym> or
- web directory.</para>
-
- <para>
- I might also recommend against a mistake that I think Debian
- has made. The terms <quote>unstable,</quote>
- <quote>testing,</quote> and <quote>experimental</quote> are
- vague and difficult to rank in order of stability (or
- instability as the case may be). Try explaining to someone
- that <quote>stable</quote> actually means <quote>ultra
- stable</quote> and that <quote>unstable</quote> doesn't
- actually include any unstable software but is really stable
- software that is untested as a distribution.
- </para>
-
- <para>
- If you are going to use branches, especially early on, keep in
- mind that people are conditioned to understand the terms
- <quote>stable</quote> and <quote>development</quote> and you
- probably can't go wrong with this simple and common division of
- branches.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Make sure all your branches are always available</term>
- <listitem>
- <para>Like a lot of this document, this should probably should
- go without saying but experience has taught me that it's not
- always obvious to people. It's a good idea to physically split
- up different branches into different directories or directory
- trees on your <acronym>FTP</acronym> or web site. Linux
- accomplishes this by having kernels in a v2.2 and a v2.3
- subdirectory where it is immediately obvious (after you know
- their version numbering scheme) which directory is for the most
- recent stable and the current development releases. Debian
- accomplishes this by naming all their distribution with names
- (i.e. woody, potato, etc.) and then changing symlinks named
- <quote>stable,</quote> <quote>unstable</quote> and
- <quote>frozen</quote> to point to which ever distribution (by
- name) is in whatever stage. Both methods work and there are
- others. In any case, it is important that different branches
- are always available, are accessible from consistent locations,
- and that different branches are clearly distinguished from each
- other so your users know exactly what they want and where to
- get it.</para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </para>
-
- </sect2>
-
-<!-- Section2: otherdev -->
-
- <sect2 id="otherdev">
- <title>Other Development issues</title>
- <para>
- There are more issues surrounding interaction with developers in a
- free software project that I can not touch on in great detail in a
- HOWTO of this size and scope. Please don't hesitate to contact me if you see
- any major omissions.
- </para>
-
- <para>
- Other smaller issues that are worth mentioning are:
- </para>
-
- <sect3 id="freezing">
- <title>Freezing</title>
- <para>
- For those projects that choose to adopt a split development model
- (<xref linkend="branches">), freezing is a concept that is worth
- becoming familiar with.
- </para>
-
- <para>
- Freezes come in two major forms. A <quote>feature freeze</quote>
- is a period when no significant functionality is added to a
- program. It is a period where established functionality (even
- skeletons of barely working functionality) can be improved and
- perfected. It is a period where bugs are fixed. This type of
- freeze is usually applied some period (a month or two) before a
- release. It is easy to push a release back as you wait for
- <quote>one more feature</quote> and a freeze helps to avoid this
- situation by drawing the much needed line in the sand. It gives
- developers room they need to get a program ready for release.
- </para>
-
- <para>
- The second type of freeze is a <quote>code freeze</quote> which
- is much more like a released piece of software. Once a piece of
- software has entered a <quote>code freeze,</quote> all changes to
- the code are discouraged and only changes that fix known bugs
- are permitted. This type of freeze usually follows a
- <quote>feature freeze</quote> and directly precedes a
- release. Most released software is in what could be interpreted
- as a sort of high level <quote>code freeze.</quote>
- </para>
-
- <para>
- Even if you never choose to appoint a release manager (<xref
- linkend="releasemanager">), you will have an easier time
- justifying the rejection or postponement of patches (<xref
- linkend="patching">) before a release with a publicly stated
- freeze in effect.
- </para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Forks</title>
- <para>
- I wasn't sure about how I would deal with forking in this
- document (or if I would deal with forking at all). A fork is when
- a group of developers takes code from a free software project and
- actually starts a brand new free software project with it. The
- most famous example of a fork was between Emacs and XEmacs. Both
- emacsen are based on an identical code-base but for technical,
- political, and philosophical reasons, development was split into
- two projects which now compete with each other.
- </para>
-
- <para>
- The short version of the fork section is, <emphasis>don't do
- them.</emphasis> Forks force developers to choose one project to
- work with, cause nasty political divisions, and redundancy of
- work. Luckily, usually the threat of the fork is enough to scare
- the maintainer or maintainers of a project into changing the way
- they run their project.
- </para>
-
- <para>
- In his chapter on <quote>The Open Source Process,</quote> Karl
- Fogel describes how to do a fork if you absolutely must. If you
- have determined that is absolutely necessary and that the
- differences between you and the people threatening to fork are
- absolutely unresolvable, I recommend Fogel's book as a good place
- to start.
- </para>
- </sect2>
- </sect1>
-
-<!-- Section1: users -->
-
- <sect1 id="users">
- <title>Maintaining a Project: Interacting with Users</title>
- <indexterm>
- <primary>fswd!users</primary>
- </indexterm>
-
- <para>
- If you've worked your way up to here, congratulations, you are
- nearing the end of this document. This final section describes some
- of the situations in which you, in your capacity as project
- maintainer, will be interacting with users. It gives some
- suggestions on how these situations might be handled effectively.
- </para>
-
- <para>
- Interacting with users is difficult. In our discussion of
- interaction with developers, the underlying assumption is that in a
- free software project, a project maintainer must constantly strive to
- attract and keep developers who can easily leave at any time.
- </para>
-
- <para>
- Users in the free software community are different than developers
- and are also different than users in the world of proprietary
- software and they should be treated differently than either
- group. Some ways in which the groups differ significantly follow:
- </para>
-
- <para>
- <itemizedlist>
-
- <listitem>
- <para>The lines between users and developers are blurred in ways
- that is totally foreign to any proprietary development
- model. Your users are often your developers and vice
- versa.</para>
- </listitem>
-
- <listitem>
- <para>In the free software world, you are often your users' only
- choice. Because there is such an emphasis on not replicating the
- work of others in the free software community and because the
- element of competition present in the propriety software model is
- absent (or at least in an extremely different form) in the free
- software development model, you will probably be the only project
- that does what you do (or at least the only one that does what
- you do in the way that you do it). This means your responsiveness
- to your users is even more important than in the proprietary
- software world.</para>
- </listitem>
-
- <listitem>
- <para>In an almost paradoxical situation, free software projects
- have less immediate or dire consequences for ignoring their users
- altogether. It is also often easier to do. Because you don't
- usually need to compete with another product, chances are good
- that you will not be scrambling to gain the features of your
- competitor's newest program. This means that your development
- process will have to be directed either internally, by a
- commitment to your users, or through both.</para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- Trying to tackle this unique situation can only be done
- indirectly. Developers and maintainers need to listen to users and
- to try and be as responsive as possible. A solid knowledge of the
- situation recounted above is any free software developer's best tool
- for shifting his development or leadership style to fit the unique
- process of free software development. This chapters will try and
- introduce some of the more difficult or important points in any
- projects interactions with users and give some hints on how to
- tackle these.
- </para>
-
-<!-- Section2: testing -->
-
- <sect2 id="testing">
- <title>Testing and Testers</title>
-
- <para>
- In addition to your users being your developers, they are also
- (and perhaps more commonly) your testers. Before I get flamed, I
- should rephrase my sentence: <emphasis>some of your
- users</emphasis> (those who explicityly volunteer) are your
- testers.
- </para>
-
- <para>
- It is important that this distinction be made early on because not
- all of your users want to be testers. Many users want to use
- stable software and don't care if they don't have the newest,
- greatest software with the latest, greatest features. These users
- except a stable, tested piece of software without major or obvious
- bugs and will be angry if they find themselves testing. This is
- yet another way in which a split development model (as mentioned
- in <xref linkend="branches">) might come in handy.
- </para>
-
- <para>
- <quote><ulink
- url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
- Projects the Open Source Way</ulink></quote> describes what a
- good test should look for:
- </para>
-
- <variablelist>
- <varlistentry>
- <term>Boundary conditions</term>
-
- <listitem>
- <para>Maximum buffer lengths, data conversions, upper/lower
- boundary limits, and so on.</para>
- </listitem>
-
- </varlistentry>
- <varlistentry>
- <term>Inappropriate behavior</term>
-
- <listitem>
- <para>Its a good idea to find out what a program will do if a
- user hands it a value it isn't expecting, hits the wrong button,
- etc. Ask yourself a bunch of <quote>what if</quote> questions
- and think of anything that <emphasis>might</emphasis> fail or
- <emphasis>might</emphasis> go wrong and find out what your
- program would do in those cases.</para>
- </listitem>
-
- </varlistentry>
- <varlistentry>
- <term>Graceful failure</term>
-
- <listitem>
- <para>The answer to a number of the <quote>what if</quote>
- questions above is probably <quote>failure</quote> which is
- often the only answer. Now make sure that it happens
- nicely. Make sure that when it crashes, there is some indication
- of why it crashed or failed so that the user or developer
- understands whats going on.</para>
- </listitem>
-
- </varlistentry>
-
- <varlistentry>
- <term>Standards conformance</term>
-
- <listitem>
- <para>If possible, make sure your programs conforms to
- standards. If it's interactive, don't be too creative with
- interfaces. If it is non-interactive, make sure it communicates
- over appropriate and established channels with other programs
- and with the rest of the system.</para>
- </listitem>
-
- </varlistentry>
- </variablelist>
-
- <sect3>
- <title>Automated testing</title>
- <para>
- For many programs, many common mistakes can be caught by
- automated means. Automated tests tend to be pretty good at
- catching errors that you've run into several times before or
- the things you just forget. They are not very good at finding
- errors, even major ones, that are totally unforeseen.
- </para>
-
- <para>
- CVS comes with a bourne shell script called sanity.sh that is
- worth looking at. Debian uses a program called lintian that
- checks Debian packages for all of the most common errors. While
- use of these scripts may not be helpful, there is a host of other
- sanity checking software on the net that may be applicable (feel
- free to email me any recommendations). None of these will create
- a bug-free release but they will avoid at least some major
- oversights. Finally, if your programs become a long term
- endeavor, you will find that there are certain errors that you
- tend to make over and over. Start a collection of scripts that
- check for these errors to help keep them out of future releases.
- </para>
- </sect3>
-
- <sect3>
- <title>Testing by testers</title>
- <para>
- For any program that depends on user interactivity, many bugs
- will only be uncovered through testing by users actually clicking
- the keys and pressing the mouse buttons. For this you need
- testers and as many as possible.
- </para>
-
- <para>
- The most difficult part of testing is finding testers. It's
- usually a good tactic to post a message to a relevant mailing
- list or news group announcing a specific proposed release date
- and outlining the functionality of your program. If you put some
- time into the announcement, you are sure to get a few responses.
- </para>
-
- <para>
- The second most difficult part of testing is
- <emphasis>keeping</emphasis> your testers and keeping them
- actively involved in the testing process. Fortunately, there are
- some tried and true tactics that can applied towards this end:
- </para>
-
- <para>
- <variablelist>
-
- <varlistentry>
- <term>Make things simple for your testers</term>
- <listitem>
- <para>Your testers are doing you a favor so make it as easy as
- possible for them. This means that you should be careful to
- package your software in a way that is easy to find, unpack,
- install, and uninstall. This also means you should explain
- what you are looking for to each tester and make the means for
- reporting bugs simple and well established. The key is to
- provide as much structure as possible to make your testers'
- jobs easy and to maintain as much flexibility as possible for
- those that want to do things a little differently.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Be responsive to your testers</term>
- <listitem>
- <para>When your testers submit bugs, respond to them and
- respond quickly. Even if you are only responding to tell them
- that the bug has already been fixed, quick and consistent
- responses make them feel like their work is heard, important,
- and appreciated.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Thank your testers</term>
- <listitem>
- <para>Thank them personally each time they send you
- patch. Thank them publicly in the documentation and the about
- section of your program. You appreciate your testers and your
- program would not be possible without their help. Make sure
- they know it. Publicly, pat them on the back to make sure the rest of
- the world knows it too. It will be appreciated more than you
- expected.</para>
- </listitem>
-
- </varlistentry>
- </variablelist>
- </para>
-
- </sect3>
- </sect2>
-
-<!-- Section2: support -->
-
- <sect2 id="support">
- <title>Setting up Support Infrastructure</title>
-
- <para>
- While testing is important, the large part of your interactions
- and responsibility to your users falls under the category of
- support. The best way to make sure your users are adequately
- supported in using your program is to set up a good infrastructure
- for this purpose so that your developers and users help each other
- and less of the burden falls on you. This way, people will also
- get quicker and better responses to their questions. This
- infrastructure comes in several major forms:
- </para>
-
- <sect3>
- <title>Documentation</title>
- <para>
- It should not come as any surprise that the key element to any
- support infrastructure is good documentation. This topic was
- large covered in <xref linkend="documentation"> and will not be
- repeated here.
- </para>
- </sect3>
-
- <sect3>
- <title>Mailing lists</title>
- <para>
- Aside from documentation, effective mailing lists will be your
- greatest tool in providing user support. Running a mailing list
- well is more complicated than installing mailing list software
- onto a machine.
- </para>
-
- <sect4>
- <title>Separate lists</title>
-
- <para>
- A good idea is too separate your user and development mailing
- lists (perhaps into project-user@host and project-devel@host)
- and enforce the division. If people post a development question
- onto -user, politely ask them to repost it onto -devel and vise
- versa. Subscribe yourself to both groups and encourage all
- primarily developers to do the same.
- </para>
-
- <para>
- This system provides so that no one person is stuck doing all of
- the support work and works so that users learn more about the
- program, they can help newer users with their questions.
- </para>
- </sect4>
-
- <sect4>
- <title>Choose mailing list software well</title>
- <para>
- Please don't make the selection of mailing list software
- impulsively. Please consider easy accessibility by users without
- a lot of technical experience so you want to be as easy as
- possible. Web accessibility to an archive of the list is also
- important.
- </para>
-
- <para>
- The two biggest free software mailing list programs are <ulink
- url="http://www.greatcircle.com/majordomo/">majordomo</ulink>
- and <ulink url="http://www.list.org/">GNU Mailman</ulink>. A
- long time advocate of majordomo, I would now recommend any
- project choose GNU Mailman. It fulfills the criteria listed
- above and makes it easier. It provides a good mailing
- list program for a free software project maintainer as opposed
- to a good mailing list application for a mailing list
- administrator.
- </para>
-
- <para>
- There are other things you want to take into consideration in
- setting up your list. If it is possible to gate your mailing
- lists to USENET and provide it in digest form as well as
- making them accessible on the web, you will please some users
- and work to make the support infrastructure slightly more
- accessible.
- </para>
- </sect4>
- </sect3>
-
- <sect3>
- <title>Other support ideas</title>
-
- <para>
- A mailing list and accessible documentation are far from all you
- can do to set up good user support infrastructure. Be
- creative. If you stumble across something that works well, email me
- and I'll include it here.
- </para>
-
- <sect4>
- <title>Make your self accessible</title>
- <para>
- You can not list too few methods to reach you. If you hang out
- in an <acronym>IRC</acronym> channel, don't hesitate to list it
- in your projects documentation. List email and snailmail
- addresses, and ways to reach you via <acronym>ICQ</acronym>,
- <acronym>AIM</acronym>, or Jabber if they apply.
- </para>
- </sect4>
-
- <sect4>
- <title>Bug management software</title>
- <para>
- For many large software projects, use of bug management software
- is essential to keep track of which bugs have been fixed, which
- bugs have not been fixed, and which bugs are being fixed by
- which people. Debian uses the <ulink
- url="http://bugs.debian.org">Debian Bug Tracking System</ulink>
- (<acronym>BTS</acronym>) although it may not be best choice for
- every project (it seems to currently be buckling under its own
- weight) As well as a damn good web browser, the mozilla project
- has spawned a sub-project resulting in a bug tracking system
- called <ulink
- url="http://www.mozilla.org/projects/bugzilla/">bugzilla</ulink>
- which has become extremely possible and which I like a lot.
- </para>
-
- <para>
- These systems (and others like them) can be unwieldy so
- developers should be careful to not spend more time on the bug
- tracking system than on the bugs or the projects themselves. If
- a project continues to grow, use of a bug tracking system can
- provide an easy standard avenue for users and testers to report
- bugs and for developers and maintainers to fix them and track
- them in an orderly fashion.
- </para>
- </sect4>
- </sect3>
- </sect2>
-
-<!-- Section2: releasing -->
-
- <sect2 id="releasing">
- <title>Releasing Your Program</title>
-
- <para>
- As mentioned earlier in the HOWTO, the first rule of releasing is,
- <emphasis>release something useful.</emphasis> Non-working or
- not-useful software will not attract anyone to your
- project. People will be turned off of your project and will be likely
- to simply gloss over it next time they see a new version
- announced. Half-working software, if useful, will intrigue people,
- whet their appetites for versions to come, and encourage them to
- join the development process.
- </para>
-
- <sect3>
- <title>When to release</title>
-
- <para>
- Making the decision to release your software for the first time
- is an incredibly important and incredibly stressful decision. But
- it needs to done. My advice is to try and make something that
- is complete enough to be usable and incomplete enough to allow
- for flexibility and room for imagination by your future
- developers. It's not an easy decision. Ask for help on a local
- Linux User Group mailing list or from a group of developer
- friends.
- </para>
-
- <para>
- One tactic is to first do an <quote>alpha</quote> or
- <quote>beta</quote> release as described below in <xref
- linkend="alphabeta">. However, most of the guidelines described
- above still apply.
- </para>
-
- <para>
- <emphasis>When you feel in your gut that it is time and you feel
- you've weighed the situation well several times, cross your
- fingers and take the plunge.</emphasis>
- </para>
-
- <para>
- After you've released for the first time, knowing when to release
- becomes less stressful, but just as difficult to gauge. I like
- the criteria offered by Robert Krawitz in his article, <ulink
- url="http://www.advogato.org/article/196.html"><quote>Free
- Software Project Management</quote></ulink> for maintaining a
- good release cycle. He recommends that you ask yourself,
- <quote>does this release...</quote>
- </para>
-
- <para>
- <itemizedlist>
- <listitem>
- <para>Contain sufficient new functionality or bug fixes to be
- worth the effort.</para>
- </listitem>
-
- <listitem>
- <para>Be spaced sufficiently far apart to allow the user time
- to work with the latest release.</para>
- </listitem>
-
- <listitem>
- <para>Be sufficiently functional so that the user can get work
- done (quality).</para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- If the answer is yes to all of these questions, its probably time
- for a release. If in doubt, remember that asking for advice can't
- hurt.
- </para>
- </sect3>
-
- <sect3>
- <title>How to release</title>
-
- <para>
- If you've followed the guidelines described in this HOWTO up
- until this point, the mechanics of doing a release are going to
- be the easy part of releasing. If you have set up consistent
- distribution locations and the other infrastructure described in
- the preceding sections, releasing should be as simple as building
- the package, checking it once over, and uploading it into the
- appropriate place and then making your website reflect the
- change.
- </para>
- </sect3>
-
- <sect3 id="alphabeta">
- <title>Alpha, beta, and development releases</title>
-
- <para>
- When contemplating releases, it worth considering the fact that
- not every release needs to be a full numbered release. Software
- users are accustomed to pre-releases but you must be careful to
- label these releases accurately or they will cause more problems then
- they are worth.
- </para>
-
- <para>
- The observation is often made that many free software developers
- seem to be confused about the release cycle. <quote><ulink
- url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
- Projects the Open Source Way</ulink></quote> suggests that you memorize
- the phrase, <quote>Alpha is not Beta. Beta is not Release</quote>
- and I'd agree that tis is a probably a good idea.
- </para>
-
- <para>
- <variablelist>
-
- <varlistentry>
- <term>alpha releases</term>
- <listitem>
- <para>Alpha software is feature-complete but sometimes only
- partially functional.</para>
-
- <para>Alpha releases are expected to be unstable, perhaps a
- little unsafe, but definitely usable. They
- <emphasis>can</emphasis> have known bugs and kinks that have
- yet to be worked out. Before releasing an alpha, be sure to
- keep in mind that <emphasis>alpha releases are still
- releases</emphasis> and people are not going to be expecting a
- nightly build from the CVS source. An alpha should work and
- have minimal testing and bug fixing already finished.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>beta releases</term>
- <listitem>
- <para>Beta software is feature-complete and functional, but is
- in the testing cycle and still has a few bugs left to be
- ironed out.</para>
-
- <para>Beta releases are general expected to be usable and
- slightly unstable, although definitely <emphasis>not
- unsafe.</emphasis> Beta releases usually preclude a full
- release by under a month. They can contain small known bugs
- but no major ones. All major functionality should be fully
- implemented although the exact mechanics can still be worked
- out. Beta releases are great tool to whet the appetites of
- potential users by giving them a very realistic view of where
- your project is going to be in the very near future and can
- help keep interest by giving people
- <emphasis>something.</emphasis></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>development releases</term>
- <listitem>
- <para><quote>Development release</quote> is much a more vague
- term than <quote>alpha</quote> or <quote>beta</quote>. I
- usually choose to reserve the term for discussion of a
- development branch although there are other ways to use the
- term. So many in fact, that I feel the term has been
- cheapened. The popular window manager <ulink
- url="http://www.enlightenment.org">Enlightenment</ulink> has
- released <emphasis>nothing but</emphasis> development
- releases. Most often, the term is used to describe releases
- that are not even alpha or beta and if I were to release a
- pre-alpha version of a piece of software in order to keep
- interest in my project alive, this is probably how I would
- have to label it.</para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- </para>
- </sect3>
- </sect2>
-
-<!-- Section2: announcing -->
-
- <sect2 id="announcing">
- <title>Announcing Your Project</title>
-
- <para>
- Well, you've done it. You've (at least for the purposes of this
- HOWTO) designed, built, and released your free software
- project. All that is left is for you to tell the world so they
- know to come and try it out and hopefully jump on board with
- development. If everything is in order as described above, this
- will be a quick and painless process. A quick announcement is all
- that it takes to put yourself on the free software community's
- radar screen.
- </para>
-
- <sect3>
- <title>Mailing lists and USENET</title>
- <para>
- Email is still the way that most people on the Internet get their
- information. Its a good idea to send a message announcing your
- program to any relevant mailing list you know of and any relevant
- USENET discussion group. Karl Fogel recommends that use you
- simple subject describing the fact that the message is an
- announcement, the name of the program, the version, and a
- half-line long description of its functionality. This way, any
- interested user or developer will be immediately attracted to
- your announcement. Fogel's example looks like:
- </para>
-
- <screen>Subject: ANN: aub 1.0, a program to assemble USENET binaries</screen>
-
- <para>
- The rest of the email should describe the programs functionality
- quickly and concisely in no more than two paragraphs and should
- provide links to the projects webpage and direct links to
- downloads for those that want to try it right away.
- </para>
-
- <para>
- You should repeat this announcement process consistently in the
- same locations for each subsequent release.
- </para>
- </sect3>
-
- <sect3>
- <title>freshmeat.net</title>
- <para>
- Mentioned earlier in <xref linkend="evalwhere">, in today's free
- software community, announcements of your project on freshmeat
- are almost more important than announcements on mailing lists.
- </para>
-
- <para>
- Visit the <ulink url="http://freshmeat.net">freshmeat.net
- website</ulink> or their <ulink
- url="http://freshmeat.net/add-project/">submit project
- page</ulink> to post your project onto their site and into their
- database. In addition to a large website, freshmeat provides a
- daily newsletter that highlights all the days releases and
- reaches a huge audience (I personally skim it every night for any
- interesting new releases).
- </para>
- </sect3>
- </sect2>
-</sect1>
-
- <bibliography>
-
- <bibliodiv>
- <title>Printed Books</title>
-
- <biblioentry>
- <biblioset>
- <author>
- <surname>Fogel</surname>
- <firstname>Karl</firstname>
- </author>
-
- <title>Open Source Development with CVS</title>
-
- <publisher>
- <publishername>Coriolois Open Press</publishername>
- </publisher>
- <pubdate>1999</pubdate>
-
- <isbn>1-57610-490-7</isbn>
-
- <abstract>
- <para>
- Fogel's <quote>guide to using CVS in the free software
- world</quote> is much more than its subitle. In the publisher's
- own words: <quote><emphasis>Open Source Development with
- CVS</emphasis> is one of the first books available that teaches
- you development and implementation of Open Source
- software.</quote> It also includes the best reference and
- tutorial to CVS I have ever seen. It is the book that was
- <emphasis>so good</emphasis> that it prompted me to write this
- HOWTO because I thought the role it tried to serve was so
- important and useful. Please check it or buy it if you can and
- are seriously interested in running a free software project.
- </para>
- </abstract>
- </biblioset>
- </biblioentry>
-
- <biblioentry
- <biblioset>
- <author>
- <surname>Lessig</surname>
- <firstname>Lawrence</firstname>
- </author>
-
- <title>Code and Other Laws of Cyberspace</title>
-
- <publisher>
- <publishername>Basic Books</publishername>
- </publisher>
- <pubdate>2000</pubdate>
-
- <isbn>0-465-03913-8</isbn>
-
- <abstract>
- <para>
- While it only briefly talks about free software (and does it by
- tiptoeing around the free software/open source issue with the
- spineless use of the term <quote>open code</quote> that only a
- laywer could coin), Lessig's book is brilliant. Written by a
- lawyer, it talks about how regulation on the Internet is not
- done with law, but with the code itself and how the nature of
- the code will determine the nature of future freedoms. In
- addition to being a quick and enjoyable read, it gives some
- cool history and describes how we <emphasis>need</emphasis>
- free software in a way more powerfully than anything I've read
- outside of <ulink
- url="http://www.gnu.org/philosophy/right-to-read.html">RMS's
- <quote>Right to Read.</quote></ulink>
- </para>
- </abstract>
- </biblioset>
- </biblioentry>
-
- <biblioentry>
- <biblioset>
- <author>
- <surname>Raymond</surname>
- <firstname>Eric</firstname>
- </author>
-
- <title>The Cathedral and the Bazaar</title>
- <subtitle>Musings on Linux and Open Source by an Accidental Revolutionary</subtitle>
-
- <publisher>
- <publishername>O'Reilly</publishername>
- </publisher>
- <pubdate>1999</pubdate>
-
- <isbn>1-56592-724-9</isbn>
- <abstract>
- <para>
- Although I have to honestly say that I am not the ESR fan that
- I used to be, this book proved invaluable in getting me where I
- am today. The essay that gives the book its title does a good
- job of sketching the free software process and does an an
- amazing job of making an argument for free software/open source
- development as a road to better software. The rest of the book
- has other of ESR's articles, which for the most part are posted
- on his website. Still, it's nice thing to own in hard copy and
- something that every free software/open source hacker should
- read.
- </para>
- </abstract>
- </biblioset>
- </biblioentry>
- </bibliodiv>
-
- <bibliodiv>
- <title>Web-Accessable Resources</title>
-
- <para>
- This is a list of the web resources pertaining to this HOWTO that
- I've found most helpful in compiling this information. If you know
- of others that would help, please don't hesitate to email me at
- <email>mako@debian.org</email> and we can look into getting it
- added to the list and represented in the HOWTO.
- </para>
-
- <para>
- I'd recommend that any free software developer (or potential one)
- skim through these sites becaue they have each have a lot to say.
- </para>
-
- <biblioentry>
- <biblioset>
- <author>
- <surname>Manley</surname>
- <firstname>Montey</firstname>
- </author>
-
- <title><ulink
- url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
- Projects the Open Source Way</ulink></title>
-
- <publisher>
- <publishername><ulink
- url="http://www.linuxprogramming.com">Linux
- Programming</ulink></publishername>
- </publisher>
- <pubdate>Oct 31, 2000</pubdate>
-
- <abstract>
- <para>
- In one of the better articles on the subject that I've read,
- Monty sums up some of the major points I touch on including:
- starting a project, testing, documenation, organizing a team and
- leadership, and several other topics. While more opiniated that
- I try to be, I think its an important article that I found very
- helpful in writing this HOWTO. I've tried to cite him in
- the places where I borrowed from him most.
- </para>
-
- <para>
- I have problems much of this piece and I recommend you read
- <xref linkend="krawitz"> at the same time you read Monty's
- article for a good critique.
- </para>
- </abstract>
- </biblioset>
- </biblioentry>
-
- <biblioentry>
- <biblioset>
- <author>
- <surname>Gabriel</surname>
- <firstname>Richard</firstname>
- </author>
-
- <title><ulink
- url="http://www.jwz.org/doc/worse-is-better.html">The Rise of
- <quote>Worse is Better</quote></ulink></title>
-
- <abstract>
- <para>
- A well written article although I think the title may have
- confused as many people as the rest of the essay helped. It
- offers a good description of how to design programs that will
- succeed and stay maintainable as they grow.
- </para>
- </abstract>
- </biblioset>
- </biblioentry>
- </bibliodiv>
-
- <bibliodiv>
- <title>Advogato Articles</title>
-
- <para>
- I've found that one of the best resources that any free software
- developer has at his or her disposal is Advogato.org. If you haven't
- yet had a chance to visit <ulink url="http://www.advogato.org">the
- website</ulink>, do.
- </para>
-
- <para>
- I have spent a huge amount of time on advogato and I've gone
- through and provided links to the articles that I think might be
- of particular interest to anyone reading this HOWTO. I think that
- skimming through these links can be helfpul and I promise that if
- you do, you'll learn a lot. You will learn that my idea of how a
- free software project should be run is not the
- <emphasis>only</emphasis> idea. I think that's important.
- </para>
-
- <para>
- If nothing else, there is <emphasis>way</emphasis> more
- information on that website than I could ever fit into, or
- reference from this HOWTO. I have listed what I think are the most
- relavant articles here with short descriptions that I've written.
- </para>
-
-
- <biblioentry>
- <biblioset>
- <author>
- <surname>Hindle</surname>
- <firstname>Stephen</firstname>
- </author>
-
- <title><ulink url="http://www.advogato.org/article/262.html">'Best Practices' for Open Source?</ulink></title>
-
- <publisher>
- <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
- </publisher>
- <pubdate>March 21, 2001</pubdate>
-
- <abstract>
- <para>
- Touching mostly on programming practice (as most articles on
- the subject usually do), the article talks a little about
- project managment (<quote>Use it!</quote>) and a bit about
- communication within a free software project.
- </para>
- </abstract>
- </biblioset>
- </biblioentry>
-
- <biblioentry>
- <biblioset>
- <author>
- <surname>Cohen</surname>
- <firstname>Bram</firstname>
- </author>
-
- <title><ulink
- url="http://www.advogato.org/article/258.html"></ulink>How to
- Write Maintainable Code</title>
-
- <publisher>
- <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
- </publisher>
- <pubdate>March 15, 2001</pubdate>
-
- <abstract>
- <para>
- This article touches upon the "writing maintainable code"
- discussion that I try hard to avoid in my HOWTO. It's one of
- the better (and most diplomatic) articles on the subject that
- I've found.
- </para>
- </abstract>
- </biblioset>
- </biblioentry>
- <biblioentry id="krawitz">
- <biblioset>
- <author>
- <surname>Krawitz</surname>
- <firstname>Robert</firstname>
- </author>
-
- <title><ulink url="http://www.advogato.org/article/196.html">Free
- Source Project Management</ulink></title>
-
- <publisher>
- <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
- </publisher>
- <pubdate>November 4, 2000</pubdate>
-
- <abstract>
- <para>
- This article made me happy because it challenged many of the
- problems that I had with Monty's article on <ulink
- url="http://www.linuxprogramming.com">LinuxProgramming</ulink>. The
- author argues that Monty calls simply for the application of
- old (proprietary software) project management techniques in
- free software projects instead of working to come up with
- something new. I found his article to be extremely well thought
- out and I think it's an essential read for any free software
- project manager.
- </para>
- </abstract>
- </biblioset>
- </biblioentry>
-
- <biblioentry>
- <biblioset>
- <author>
- <surname>Martins</surname>
- <firstname>Lalo</firstname>
- </author>
-
- <title><ulink url="http://www.advogato.org/article/128.html">Ask
- the Advogatos: why do Free Software projects
- fail?</ulink></title>
-
- <publisher>
- <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
- </publisher>
- <pubdate>July 20, 2000</pubdate>
-
- <abstract>
- <para>
- While the article is little more than a question, reading the
- answers to this question offered by advogato's readers can
- help. In a lot of ways, this HOWTO acts as my answer to the
- questions posed in this article but there are others, many of
- which might take issue with whats is in this HOWTO. It's worth
- checking out.
- </para>
- </abstract>
- </biblioset>
- </biblioentry>
-
- <biblioentry>
- <biblioset>
- <author>
- <surname>Burley</surname>
- <firstname>David</firstname>
- </author>
-
- <title><ulink
- url="http://www.advogato.org/article/107.html">In-Roads to Free
- Software Development</ulink></title>
-
- <publisher>
- <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
- </publisher>
- <pubdate>June 14, 2000</pubdate>
-
- <abstract>
- <para>
- This document was written as a response to <ulink
- url="http://www.advogato.org/article/72.html">another advogato
- article</ulink>. Although not about running a project, this
- describes some of the ways that you can get started with free
- software development without starting a project. I think this
- is an important article. If you are interested in becoming
- involved with free software, this article showcases some of the
- ways that you can do this without actually starting a project
- (something that I hope this HOWTO has demonstrated is not to be
- taken lightly).
- </para>
- </abstract>
- </biblioset>
- </biblioentry>
-
- <biblioentry>
- <biblioset>
- <author>
- <surname>Moorman</surname>
- <firstname>Jacob</firstname>
- </author>
-
- <title><ulink
- url="http://www.advogato.org/article/72.html"></ulink>Importance
- of Non-Developer Supporters in Free Software</title>
-
- <publisher>
- <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
- </publisher>
- <pubdate>April 16, 2000</pubdate>
-
- <abstract>
- <para>
- Moorman's is a short article but it brings up some good
- points. The comment reminding developers to thank their testers
- and end-users is invaluable and oft-forgotten.
- </para>
- </abstract>
- </biblioset>
- </biblioentry>
-
- <biblioentry>
- <biblioset>
- <author>
- <surname>Orchard</surname>
- <firstname>Leslie</firstname>
- </author>
-
- <title><ulink url="http://www.advogato.org/article/67.html">On
- Naming an Open Source Project</ulink></title>
-
- <publisher>
- <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
- </publisher>
- <pubdate>April 12, 2000</pubdate>
-
- <abstract>
- <para>
- I didn't even have a section on project naming in this HOWTO
- (See <xref linkend="naming">) until Leslie Orchard's article
- reminded me of it. Thanks to Leslie for writing this article!
- </para>
- </abstract>
- </biblioset>
- </biblioentry>
-
- <biblioentry>
- <biblioset>
- <author>
- <surname>Allen</surname>
- <firstname>David</firstname>
- </author>
-
- <title><ulink url="http://www.advogato.org/article/40.html">Version Numbering Madness</ulink></title>
-
- <publisher>
- <publishername><ulink url="http://www.advogato.org">Advogato</ulink></publishername>
- </publisher>
- <pubdate>Februrary 28, 2000</pubdate>
-
- <abstract>
- <para>
- In this article, David Allen challengs the whole
- <quote>Major.Minor.Patch</quote> version numbering scheme. Its
- good to read this as you read <xref
- linkend="chooseversioning">. I liked the article and it
- describes some of the projects that I bring up in my discussion
- of verion numbering.
- </para>
- </abstract>
- </biblioset>
- </biblioentry>
-
- </bibliodiv>
- </bibliography>
-
-</article>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-namecase-general:t
-sgml-general-insert-case:lower
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:nil
-sgml-parent-document:nil
-sgml-exposed-tags:nil
-sgml-local-catalogs:nil
-sgml-local-ecat-files:nil
-End:
--->
\ No newline at end of file
projects / fspm_howto / commitdiff