X-Git-Url: https://projects.mako.cc/source/fspm_howto/blobdiff_plain/b0f1af3d6820e8c60139c20bff832aad1862a9b3..57bccb28ad9f1356de427fd1156afff43abddce6:/FreeSoftwareDevelopmentHOWTO.sgml
diff --git a/FreeSoftwareDevelopmentHOWTO.sgml b/FreeSoftwareDevelopmentHOWTO.sgml
index 407322c..19375fd 100644
--- a/FreeSoftwareDevelopmentHOWTO.sgml
+++ b/FreeSoftwareDevelopmentHOWTO.sgml
@@ -6,57 +6,60 @@
Free Software Development HOWTO
-
+
- Benjamin
- Mako
- Hill
-
-
- mako@debian.org
-
-
-
+ Benjamin
+ Mako
+ Hill
+
+
+ mako@debian.org
+
+
-
-
-
- v0.01
- 27 March 2001
- bch
-
- Initial Release
-
-
-
+
+
+
+ v0.2
+ 8 April 2001
+ bch
+
+
+
+ v0.01
+ 27 March 2001
+ bch
+ Initial Release
+
+
-
- fswd
-
-
-
- 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 act as a crash course in the people skills
- that aren't taught to commercial coders but that can make or
- break a free software project.
-
+
+ fswd
+
+
+
+ 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 act as a crash course in the people skills that
+ aren't taught to commercial coders but that can make or break a
+ free software project.
+
-
+
- Introduction
-
-
- fswd!introduction
-
-
+ Introduction
+
+
+ fswd!introduction
+
+
Skimming through freshmeat.net provides mountains of reasons for this
HOWTO's existence--the Internet is littered with excellently
@@ -414,6 +417,17 @@
early on. Find out exactly what it is that you want your project
to do.
+
+
+ Monty Manley articles the importance of this initial step in an
+ essay, Managing
+ Projects the Open Source Way. As the next section will
+ show, there is a lot of work that needs to
+ be done before software is ready for release. Manley says,
+ Beginning an OSS project properly means that a developer
+ must, first and foremost, avoid writing code too soon!
+
@@ -564,6 +578,61 @@
+
+
+
+ Naming your project
+
+
+ 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 advogato
+ article. The article is short and probably worth looking
+ over quickly.
+
+
+
+ The very short version is that Orchard recommends that you should
+ pick a name where, after hearing the name, many users or
+ developers will:
+
+
+
+
+
+ You will know what the project does.
+
+
+ You will remember it tomorrow.
+
+
+
+
+
+ Humorously, Orchard's project, Iajitsu, does neither (and
+ development is effectively frozen since the article was written).
+
+
+
+ There is a point though. There are companies who only job is to
+ make names for pieces of software. They make
+ ridiculous 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.
+
+
+
+ If there is a name you really want, go ahead. I though
+ gnubile
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.
+
+
+
@@ -795,6 +864,32 @@ for details.
than 2.0.005.
+
+ Beyond this, the most common technique seems to be the
+ major level
, minor level
,
+ patch level
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.
+
+
+
+ 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.
+
+
+
+ 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.
+
+
Follow these two simple rules and you will not go (too)
wrong. Still, there are several version numbering systems that are
@@ -901,11 +996,12 @@ for details.
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. 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. This being
+ the case, this section deals mostly useful tactics for
+ user-directed documentation.
@@ -1236,6 +1332,32 @@ pages for more information and options.
+
+ 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 posted HTML version)
+ wholeheartedly.
+
+
+
+ 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 SourceForge do a great job
+ as well with a nice, easy to use interface to CVS.
+
+
+
+ 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.
+
@@ -1327,6 +1449,23 @@ pages for more information and options.
ways you can do this:
+
+ 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. Managing
+ Projects the Open Source Way argues that 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).
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.
+
+
How to delegate
@@ -1931,6 +2070,72 @@ pages for more information and options.
linkend="branches">) might come in handy.
+
+ Managing
+ Projects the Open Source Way describes what a good test
+ should look for in each module:
+
+
+
+
+ Boundary conditions
+
+
+
+ Maximum buffer lengths, data conversions, upper/lower boundary
+ limits, and so on.
+
+
+
+
+
+ Inappropriate behavior
+
+
+
+ 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 might fail or
+ might go wrong and find out what program
+ would do in that case.
+
+
+
+
+
+ Graceful failure
+
+
+
+ The answer to a number of the what if
questions
+ above is probably failure
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.
+
+
+
+
+
+
+ Standards conformance
+
+
+
+ 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.
+
+
+
+
+
+
Automated testing
@@ -2208,6 +2413,41 @@ pages for more information and options.
you've weighed the situation well several times, cross your
fingers and take the plunge.
+
+
+ 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, Free
+ Software Project Management
for maintaining a
+ good release cycle. He recommends that you ask yourself,
+ does this release...
+
+
+
+
+
+ Contain sufficient new functionality or bug fixes to be
+ worth the effort.
+
+
+
+ Be spaced sufficiently far apart to allow the user time
+ to work with the latest release.
+
+
+
+ Be sufficiently functional so that the user can get work
+ done (quality).
+
+
+
+
+
+ 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.
+
@@ -2236,12 +2476,24 @@ pages for more information and options.
they are worth.
+
+ The observation is often made that many free software developers
+ seem to be confused about the release cycle. Managing
+ Projects the Open Source Way suggests that you memorize
+ the phrase, Alpha is not Beta. Beta is not Release
+ and I'd agree that tis is a probably a good idea.
+
+
alpha releases
+ Alpha software is feature-complete but sometimes only
+ partially functional.
+
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
@@ -2257,6 +2509,9 @@ pages for more information and options.
beta releases
+ Beta software is feature-complete and functional, but is
+ in the testing cycle and still has a few bugs in it.
+
Beta releases are general expected to be usable and
slightly unstable, although definitely not
unsafe. Beta releases usually preclude a full
@@ -2363,6 +2618,435 @@ pages for more information and options.
+
+
+
+ Printed Books
+
+
+
+
+ Fogel
+ Karl
+
+
+ Open Source Development with CVS
+
+
+ Coriolois Open Press
+
+ 1999
+
+ 1-57610-490-7
+
+
+
+ Fogel's Guide to using CVS in the free software
+ world
is much more than its subitle. In the publishers
+ own words: Open Source Development with
+ CVS is one of the first books available that teaches
+ you development and implementation of Open Source
+ software.
It includes the best reference and tutorial
+ to CVS I have ever seen. It is the book that was so
+ good 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.
+
+
+
+
+
+
+
+ Lessig
+ Lawrence
+
+
+ Code and Other Laws of Cyberspace
+
+
+ Basic Books
+
+ 2000
+
+ 0-465-03913-8
+
+
+
+ While it only briefly talks about free software (and does it by
+ tiptoeing around the free software/open source issue with the
+ term open code
), 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
+ need free software in a way more
+ powerfully than anything I've read (outside of RMS's
+ Right to Read.
+
+
+
+
+
+
+
+
+ Raymond
+ Eric
+
+
+ The Cathedral and the Bazaar
+ Musings on Linux and Open Source by an Accidental Revolutionary
+
+
+ O'Reilly
+
+ 1999
+
+ 1-56592-724-9
+
+
+ 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.
+
+
+
+
+
+
+
+ Web-Accessable Resources
+
+
+ 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
+ mako@debian.org and we can look into getting it
+ added on the list.
+
+
+
+ I'd recommend that any free software developer (or potential one)
+ skim through these sites becaue they have a lot to say.
+
+
+
+
+
+ Manley
+ Montey
+
+
+ <ulink
+ url="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD">Managing
+ Projects the Open Source Way</ulink>
+
+
+ Linux
+ Programming
+
+ Oct 31, 2000
+
+
+
+ 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 at the same time you read Monty's
+ article.
+
+
+
+
+
+
+
+
+ Gabriel
+ Richard
+
+
+ <ulink
+ url="http://www.jwz.org/doc/worse-is-better.html">The Rise of
+ <quote>Worse is Better</quote></ulink>
+
+
+
+ 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.
+
+
+
+
+
+
+
+ Advogato Articles
+
+
+ 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 the website, do.
+
+
+
+ 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 only idea about how such a
+ project can be done. I think that's great.
+
+
+
+ If nothing else, there is way 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.
+
+
+
+
+
+
+ Hindle
+ Stephen
+
+
+ <ulink url="http://www.advogato.org/article/262.html">'Best Practices' for Open Source?</ulink>
+
+
+ Advogato
+
+ March 21, 2001
+
+
+
+ Touching mostly on programming practice (as most articles on
+ the subject usually do), the article talks a little about
+ project managment (Use it!
) and a bit about
+ communication within a free software project.
+
+
+
+
+
+
+
+
+ Cohen
+ Bram
+
+
+ <ulink
+ url="http://www.advogato.org/article/258.html"></ulink>How to
+ Write Maintainable Code
+
+
+ Advogato
+
+ March 15, 2001
+
+
+
+ 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.
+
+
+
+
+
+
+
+ Krawitz
+ Robert
+
+
+ <ulink url="http://www.advogato.org/article/196.html">Free
+ Source Project Management</ulink>
+
+
+ Advogato
+
+ November 4, 2000
+
+
+
+ This article made me happy because it challenged many of the
+ problems that I had with Monty's article on LinuxProgramming. 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.
+
+
+
+
+
+
+
+
+ Martins
+ Lalo
+
+
+ <ulink url="http://www.advogato.org/article/128.html">Ask
+ the Advogatos: why do Free Software projects
+ fail?</ulink>
+
+
+ Advogato
+
+ July 20, 2000
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+ Burley
+ David
+
+
+ <ulink
+ url="http://www.advogato.org/article/107.html">In-Roads to Free
+ Software Development</ulink>
+
+
+ Advogato
+
+ June 14, 2000
+
+
+
+ This document was written as a response to another advogato
+ article. 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).
+
+
+
+
+
+
+
+
+ Moorman
+ Jacob
+
+
+ <ulink
+ url="http://www.advogato.org/article/72.html"></ulink>Importance
+ of Non-Developer Supporters in Free Software
+
+
+ Advogato
+
+ April 16, 2000
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+ Orchard
+ Leslie
+
+
+ <ulink url="http://www.advogato.org/article/67.html">On
+ Naming an Open Source Project</ulink>
+
+
+ Advogato
+
+ April 12, 2000
+
+
+
+ I didn't even have a section on naming in this HOWTO (See ) until Leslie Orchard's article reminded me
+ of it. Thanks to Leslie for writing this article!
+
+
+
+
+
+
+
+
+ Allen
+ David
+
+
+ <ulink url="http://www.advogato.org/article/40.html">Version Numbering Madness</ulink>
+
+
+ Advogato
+
+ Februrary 28, 2000
+
+
+
+ In this article, David Allen challengs the whole
+ Major.Minor.Patch
versioning scheme. Its good to
+ read this as you read . I
+ liked the article and it describes some of the projects that I
+ bring up in my discussion of verion numbering.
+
+
+
+
+
+
+
+