X-Git-Url: https://projects.mako.cc/source/fspm_howto/blobdiff_plain/986b7e4aa0982f54d51719fee337383fc86dcd06..57bccb28ad9f1356de427fd1156afff43abddce6:/FreeSoftwareDevelopmentHOWTO.sgml diff --git a/FreeSoftwareDevelopmentHOWTO.sgml b/FreeSoftwareDevelopmentHOWTO.sgml index 74401a8..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 @@ -1380,8 +1519,8 @@ pages for more information and options. 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 who lead who can do - nothing but delegate can serve as a + helpful. Debian's idea of a project leader who can do + nothing 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. @@ -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. + + + + + + + +