If you've worked your way up to here, congratulations, you are nearing the end of this document. This final section describes some of the situations in which you, in your capacity as project maintainer, will be interacting with users. It gives some suggestions on how these situations might be handled effectively.
Interacting with users is difficult. In our discussion of interaction with developers, the underlying assumption is that in a free software project, a project maintainer must constantly strive to attract and keep developers who can easily leave at any time.
Users in the free software community are different than developers and are also different than users in the world of proprietary software and they should be treated differently than either group. Some ways in which the groups differ significantly follow:
The lines between users and developers are blurred in ways that is totally foreign to any proprietary development model. Your users are often your developers and vice versa.
In the free software world, you are often your users' only choice. Because there is such an emphasis on not replicating the work of others in the free software community and because the element of competition present in the propriety software model is absent (or at least in an extremely different form) in the free software development model, you will probably be the only project that does what you do (or at least the only one that does what you do in the way that you do it). This means your responsiveness to your users is even more important than in the proprietary software world.
In an almost paradoxical situation, free software projects have less immediate or dire consequences for ignoring their users altogether. It is also often easier to do. Because you don't usually need to compete with another product, chances are good that you will not be scrambling to gain the features of your competitor's newest program. This means that your development process will have to be directed either internally, by a commitment to your users, or through both.
Trying to tackle this unique situation can only be done indirectly. Developers and maintainers need to listen to users and to try and be as responsive as possible. A solid knowledge of the situation recounted above is any free software developer's best tool for shifting his development or leadership style to fit the unique process of free software project management. This chapters will try and introduce some of the more difficult or important points in any projects interactions with users and give some hints on how to tackle these.
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: some of your users (those who explicitly volunteer) are your testers.
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 Section 3.3) might come in handy.
"Managing Projects the Open Source Way" describes what a good test should look for:
Maximum buffer lengths, data conversions, upper/lower boundary limits, and so on.
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 your program would do in those cases.
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.
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.
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.
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.
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.
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.
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 toward this end:
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.
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.
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.
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:
It should not come as any surprise that the key element to any support infrastructure is good documentation. This topic was largely covered in Section 2.5 and will not be repeated here.
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.
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.
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.
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.
The two biggest free software mailing list programs are majordomo and GNU Mailman. 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.
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.
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.
You can not list too few methods to reach you. If you hang out in an IRC channel, don't hesitate to list it in your projects documentation. List email and snailmail addresses, and ways to reach you via ICQ, AIM, or Jabber if they apply.
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 Debian Bug Tracking System (BTS) 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 bugzilla which has become extremely possible and which I like a lot.
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.
As mentioned earlier in the HOWTO, the first rule of releasing is, release something useful. 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.
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.
One tactic is to first do an "alpha" or "beta" release as described below in Section 4.3.3. However, most of the guidelines described above still apply.
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.
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.
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.
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.
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 software is feature-complete but sometimes only partially functional.
Alpha releases are expected to be unstable, perhaps a little unsafe, but definitely usable. They can have known bugs and kinks that have yet to be worked out. Before releasing an alpha, be sure to keep in mind that alpha releases are still releases 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.
Beta software is feature-complete and functional, but is in the testing cycle and still has a few bugs left to be ironed out.
Beta releases are general expected to be usable and slightly unstable, although definitely not 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 to be in the very near future and can help keep interest by giving people something.
"Development release" is much a more vague term than "alpha" or "beta". 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 Enlightenment has released nothing but 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.
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.
Announce your software on Usenet's comp.os.linux.announce. If you only announce your software in two places, have it be c.o.l.a and freshmeat.
However, 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 other relevant Usenet discussion groups.
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:
Subject: ANN: aub 1.0, a program to assemble Usenet binaries |
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. This form will work for both Usenet and mailing list posts.
You should repeat this announcement process consistently in the same locations for each subsequent release.
Mentioned earlier in Section 2.1.2.1, in today's free software community, announcements of your project on freshmeat are almost more important than announcements on mailing lists.
Visit the freshmeat.net website or their submit project page 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).
If you've gone ahead and created mailing lists for your project, you should always announce new versions on these lists. I've found that for many projects, users request a very low-volume announce only mailing list to be notified when new versions are released. freshmeat.net now allows users to subscribe to a particular project so they receive emails every time a new version is announced through their system. It's free and it can stand in for an announce-only mailing list. In my opinion, it can't hurt.