<revhistory>
<revision>
<revnumber>v0.2</revnumber>
- <date>7 April 2001</date>
+ <date>8 April 2001</date>
<authorinitials>bch</authorinitials>
</revision>
early on. Find out exactly what it is that you want your project
to do.
</para>
+
+ <para>
+ Monty Manley articles the importance of this initial step in an
+ essay, <ulink
+ url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
+ Projects the Open Source Way.</ulink> As the next section will
+ show, there is <emphasis>a lot</emphasis> of work that needs to
+ be done before software is ready for release. 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>
</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 wroth giving a little bit of thought. Leslie Orchard
+ tackles this issue in a n <ulink
+ url="http://www.advogato.org/article/67.html">advogato
+ article</ulink>. The article is short and probably worth looking
+ over quickly.
+ </para>
+
+ <para>
+ The very short version is that Orchard recommends that you should
+ pick a name where, after hearing the name, many users or
+ developers will:
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>You will know what the project does.</para>
+ </listitem>
+ <listitem>
+ <para>You will remember it tomorrow.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Humorously, Orchard's project, Iajitsu, does neither (and
+ development is effectively frozen since the article was written).
+ </para>
+
+ <para>
+ There is a point though. There are companies who only job is to
+ make names for pieces of software. They make
+ <emphasis>ridiculous</emphasis> amount of money doing it and they
+ 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.
+ </para>
+
+ <para>
+ If there is a name you really want, go ahead. I though
+ <quote>gnubile</quote> was one of the best names ever and I still
+ talk about it, long after I've stopped using the program. If you
+ can flexible on the subject, listen to Orchard's advice. It might
+ even help you.
+ </para>
+ </sect2>
+
<!-- Section2: licensing-->
<sect2 id="licensing">
than 2.0.005.
</para>
+ <para>
+ 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 it 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 bug fixes.
+ </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. Beware, if you
+ choose to, someone will get annoyed, assume you don't know, and
+ try and educate you. I always follow this method and I implore you
+ to do so as well.
+ </para>
+
<para>
Follow these two simple rules and you will not go (too)
wrong. Still, there are several version numbering systems that are
<para>
There are lots of different people for whom to document and
- therefore there are lots of ways to document your project. The
- idea of documentation in source code to help facilitate
- development by a large community is vital but it falls outside the scope
- of this HOWTO. This being the case, this section deals mostly
- useful tactics for user-directed documentation.
+ therefore there are lots of ways to document your
+ project. <emphasis>The importance of ocumentation in source code
+ to help facilitate development by a large community is vital but
+ it falls outside the scope of this HOWTO.</emphasis> This being
+ the case, this section deals mostly useful tactics for
+ user-directed documentation.
</para>
<para>
</itemizedlist>
</para>
+ <para>
+ A version control system can make a lot of these problems of
+ packaging (and a lot of other problems mentioned in this HOWTO)
+ much easier. 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 introduced into this HOWTO.
+ I am not aware of any free version control systems for windows or
+ mac 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 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 version straight on this HOWTO!) but I
+ think it falls outside the scope of this document and should/has
+ already have its own HOWTO written about it.
+ </para>
</sect3>
</sect2>
</sect1>
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 been the death of a project. <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
+ projects founder and that these important powers need not all rest
+ in one person but that a release manager may be different than a
+ lead developer. These situations are tricky politically though so
+ be careful and make sure this is necessary before you go around
+ empowering people.
+ </para>
+
<sect3>
<title>How to delegate</title>
linkend="branches">) might come in handy.
</para>
+ <para>
+ <ulink
+ url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
+ Projects the Open Source Way</ulink> describes what a good test
+ should look for in each module:
+ </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 what if questions and think of
+ anything that <emphasis>might</emphasis> fail or
+ <emphasis>might</emphasis> go wrong and find out what program
+ would do in that case.
+ </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. 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>
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>
they are worth.
</para>
+ <para>
+ The observation is often made that many free software developers
+ seem to be confused about the release cycle. <ulink
+ url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
+ Projects the Open Source Way</ulink> 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. Alpha versions should
have full functionality and limited testing. They can have
<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 in it.</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
</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 publishers
+ 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 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 information it helped distribute was so important
+ and useful. Please check it or by 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
+ term <quote>open code</quote>), Lessig 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 future
+ freedoms. In addition to being a quick and enjoyable read, it
+ gives some cool history 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 sketching the free software process and does an an amazing
+ of job of making an argument for free software/open source
+ development as making better software. The rest of the book has
+ other articles, for the most part posted on his website, but
+ it's nice thing to own in hard copy and something 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 resources pertaining to this HOWTO that I've
+ found most helpful in compiling this information. If you have
+ more, please don't hesitate to email me at
+ <email>mako@debian.org</email> and we can look into getting it
+ added on the list.
+ </para>
+
+ <para>
+ I'd recommend that any free software developer (or potential one)
+ skim through these sites becaue they 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, orgazing 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 and that I've tried to cite it in
+ the places where I borrowed from it most. I have problems with
+ much of the things written in the piece and I recommend you
+ read <xref linkend="krawitz"> at the same time you read Monty's
+ article.
+ </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 it 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 the advogato. 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 lot of time on advogato and I've gone through and
+ provided links to the articles that I think are of particular
+ interest to anyone reading this HOWTO. I think that looking
+ through these is important. I promise that 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 about how such a
+ project can be done. I think that's great.
+ </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.
+ </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 discussion. It's one
+ of the better 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 argues simply for the application of
+ old project management techniques to free software projects
+ instead of working with something new. I found his article to
+ be extremely well thought out and I think its an essential read
+ for any 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
+ answer to this question can help. In a lot of ways, this HOWTO
+ acts as my answer to the question posed in this article but
+ there are others, many of which might take issue with whats 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. I think this is an important article. If
+ you are interested to become 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 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> versioning 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
projects / fspm_howto / blobdiff