+
+ <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</emphasis> users are
+ your testers.
+ </para>
+
+ <para>
+ It is important that this distinction be made early on because not
+ all of your users wants 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 and greatest features. These
+ users except a stable, tested piece of software with major or
+ obvious bugs worked out or openly declared and will be angry if
+ they find themselves in a testing position. This is yet another
+ way in which a split development model (as mentioned in <xref
+ linkend="branches">) might come in handy.
+ </para>
+
+ <sect3>
+ <title>Automated testing</title>
+ <para>
+ For many programs, many common and 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
+ something you just forget and not very good at finding errors,
+ even major ones, that were 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
+ using these scripts may not be possible, there is a host of other
+ sanity checking software on the net that may be applicable (feel
+ free to email 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 prevent them in the future.
+ </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 testers 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 outline the functionality of the program. If you put some
+ time into the announcement, you are sure to get a few bites.
+ </para>
+
+ <para>
+ The second most difficult part of testing is keeping 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>
+ <itemizedlist>
+
+ <listitem>
+ <para><emphasis>Make things simple for your testers.</emphasis>
+ Your testers are doing you a favor so make it as easy as
+ possible. 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 tester's job easy and
+ maintain as much flexibility as possible for those that want to
+ do things a little differently.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Be responsive to your testers.</emphasis> 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 response make
+ them feel like their work is heard, important, and
+ appreciated.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Thank your testers.</emphasis> 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 and pat them on the
+ back by making sure the rest of the world knows it too. It will
+ be appreciated more than you expected.</para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+ </sect3>
+ </sect2>
+
+<!-- Section2: support -->
+
+ <sect2 id="support">
+ <title>Setting up a 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 while people get quicker and
+ better responses to their questions. This infrastructure comes in
+ several 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 supporting 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 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 new 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
+ lightly. 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 to do. 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 in setting up your
+ list. If it is possible to gate your mailing lists to USENET and
+ provide them 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 all you can do to set
+ up good user support infrastructure. Be creative. If you stumble
+ across something works well, email me and I'll include it here in
+ the HOWTO.
+ </para>
+ <sect4>
+ <title>Make your self accessible</title>
+ <para>
+ You can not put to few methods to access you. If you hang out in
+ an <acronym>IRC</acronym> channel, don't hesitate to list in
+ your projects documentation. List email and snail mail
+ addresses, or ways to reach you via <acronym>ICQ</acronym>,
+ <acronym>AIM</acronym>, or Jabber.
+ </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>.
+ </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 way for users and testers to report
+ bugs and for developers and maintainers to fix 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 or 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 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 the version 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 be done. My advice is to try and make something that
+ is complete enough to be usable and incomplete enough to allow
+ for flexibility and 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 it is time and you feel
+ you've weighed the situation well several times, cross your
+ fingers and take the plunge.</emphasis>
+ </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 a 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 reflecting the release on
+ your website.
+ </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 cause more problems then
+ they are worth.
+ </para>
+
+ <para>
+ <variablelist>
+
+ <varlistentry>
+ <term>alpha releases</term>
+ <listitem>
+ <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 known
+ bugs and kinks that have yet to be worked out. Before 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 releases are general expected to be usable and
+ slightly unstable, although definitely
+ <emphasis>not</emphasis> unsafe. 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 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>
+ Development release is much more vague term than
+ <quote>alpha</quote> or <quote>beta</quote>. I usually choose
+ to reserve the term for discussion of a development
+ branch. 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 to alpha or beta stages though and if I
+ were to release a pre-alpha release in order to keep interest
+ in my project live, 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 communities
+ 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 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 list
+ announcements.
+ </para>
+
+ <para>
+ Visit the <ulink url="http://freshmeat.net">freshmeat
+ website</ulink> or their <ulink
+ url="http://freshmeat.net/add-project/">submit project
+ page</ulink> to post your project on their site and in 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 skim it every night for any
+ interesting new releases).
+ </para>
+
+ <para>
+ Once you've finished this...
+ </para>
+
+ <para>
+ Congratulations. You've now the maintainer of an active free
+ software project. Good luck and feel free to stay in touch with
+ me about your experiences. I'd love to incorporate them into this
+ HOWTO.
+ </para>
+ </sect3>
projects / fspm_howto / blobdiff