+
+ <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
+ largely 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>
projects / fspm_howto / blobdiff