CSE 403, Spring 2009
Assignment #5: Zero-Feature Release

Due: Thursday, April 30, by 10:00pm
Turnin: Link

The Zero-Feature Release (ZFR) milestone consists of a skeletal implementation of your product. The initial implementation must be able to be installed and run, but running it does not have to do anything except display an initial window, webpage, or whatever your UI displays. This milestone will help you to ensure that your toolchain (version control, bug tracking, deployment, etc.) is operational.

Your entire submission will consist of a single URL — the webpage for your product. The webpage should include information about your product, including how to obtain the current release.

All information on your webpage should appear in your version control repository. (If something is not in your repository, then it might as well not exist.) In particular, it should be possible for someone not on your team to check out a copy of your repository, build according to your instructions, and then work solely from the copy. And this is, in fact, what the staff will do, in order to ensure that all the information is in your repository. You may continue committing to your repository — the staff will check out a version as of the due date, so we will be insulated from subsequent changes to the repository or website.

Like any open-source software, your project will ship with documentation of two types: that for end users, and that for developers. The product homepage should be focused on end users, but developers should be able to use it to find the information that they want, including where to find your repository.

Don't forget to include a plain-text README file or a README.html file in the top-level directory of your distribution and your repository. At a minimum, it should contain a pointer to your user and developer documentation.

Documentation for users

Your documentation for users should include at least the following information:

• a description of your project, such as what it does, what is unique about it, and why a user would want to use it.
• how to obtain and install the software. For hosted software such as a website, the installation instructions may be empty. Other specialized platforms may have their own conventions. For desktop software, the installation instructions would include a list of all prerequisites (e.g., tools, libraries, emulators, etc.) and information about how to install them (possibly just a pointer to the documentation of the external software. Assume a user on one of the departmental Unix servers, though you may additionally provide instructions for other platforms (Windows, non-department Unix machine, mobile phone, etc.).
• how to run the software (that is, how to start it up). In some cases, the instructions may need to include information such as how to access data sources (e.g., how to create and populate a database), or other customization information.
• a high-level description of the user view of your software. Questions you might answer include the following. What is the concept around which the UI or user experience is organized (example: a canvas) and the way in which the user interacts or performs specific actions? Is the software designed by analogy to some other software, or to some process in the real world? Are there modes? What is the workflow?
  For some software, this section may be short. The more powerful your software (and the more it is aimed at sophisticated users), the greater the need for an overview of its operation and scope. Online help is very useful, but it is no substitute for an explanation of your product's concepts from the point of view of a user!
• how to use the software. Again, include an appropriate level of detail, and there is no need to belabor anything that is obvious. Assume that your user is familiar with your particular platform (e.g., use of a Web browser, desktop applications, or a mobile phone).
• how to report a bug. This should include not just the mechanics (a URL or email address), but also what information is needed. You might want to reference a resource about how to write a good bug report: Sun, Mozilla, Ximian, Tatham, Raymond.
  Your list of bugs should ideally be publicly accessible; if so, your documentation should indicate how to access the list to prevent users from submitting duplicates.

You might choose to make the product homepage be the same as the user manual, or make them separate, with the homepage linking to the user manual. If the user manual is a separate document, it may be in HTML, PDF, or some other format that you think is reasonable (get staff approval first). The homepage and other documentation does not have to be visually elaborate or use over-the-top web design, but it must be informative.

Documentation for developers

Your documentation for developers must include information for someone who wishes to contribute to your project as a developer, to create a customized version, to pick up development where you left off, etc. It should include at least the following information:

• How to obtain the source code, including at a minimum:
  • How to obtain the source code for the latest stable/released version. (See our recommendation below.)
  • Where to find the source code repository that you use for development. We recommend use of the Subversion repository that the staff set up for you. Otherwise, make sure that the course staff has access. (We will periodically check it to ensure that your group is making consistent progress.)
• The layout of your directory structure: what the various directories (folders) contain, or where to find important information such as source files, documentation, data files, etc.
• How to build the software (e.g., compile it). In some cases, such as if you are building a standalone application using an interpreted language, there may not be any build instructions. If so, you should state that explicitly, since developers will expect build instructions and their absence may be confusing.
• How to test the software (e.g., run the test suite). In some cases, the instructions may need to include information such as how to access data sources (e.g., how to create and populate a database), similarly to or in addition to what a user must do. For example if your software is a website or web service, the developer documentation must include everything a programmer must do in order to get a test version of the website up and running your software.
• How to set up an automated daily (or more frequent) build and test. For your daily build and test, you may wish to use cron (cronic is a nice script to wrap your cron job), CruiseControl, or similar software. Describe how you set up your daily build and test system, and how you ensured that any failure output is emailed to your entire team. (Don't describe how you might have done it or how you plan to do it; actually do it, and describe what you did.) It is a requirement that before the due date, at least one failing daily test result is automatically emailed to the team. This obviously requires that at least some tests already exist.
• How to release a new version of your software. After you are happy that a new version of your product is ready to be released, making a release involves steps such as:
  • updating revision numbers in your code and documentation.
  • creating the zip file, tar file, or other package that a user or developer will download to obtain your product. If you have multiple downloads (say, a source and a binary release), then each must be created.
  • copying files to your website, so that the new version is visible to the world.
  • sanity-checking that the website and downloadable files are as you wish. For instance, check that all the links work, download the software and run its tests, etc.
  Your instructions should make clear how to control the website to which your files are copied. For example, developers must be able to create a private release (sometimes called a testing release). That way, you can test your software without breaking the publicly-available version. It is permissible to create a testing release on an automated schedule (say, every night). However, you should update your main public release only when your code is in a stable state for ordinary users.
• How to access the list of outstanding bugs and the list of resolved bugs, and how to resolve a bug. (If you are using an off-the-shelf bug tracking system, your instructions may be trivial.)
  For the ZFR, your bug tracking system need not have a comprehensive list of every last bug and missing feature. However, if your customer (e.g., the course staff) runs across a problem while using your software, you will regain some credit if the bug tracking system contains a description of the problem.
• The source code should contain comments. At a minimum, every file should have a comment describing its purpose and, if appropriate or not obvious, how it fits into your overall design. Also, every procedure is required to have at least a one-sentence comment describing what it does — or more if appropriate. Often, comments may also note who is responsible; but you can tell this from the version control system, so some people consider it clutter.

All of the tasks (running, compiling, and releasing your software) should work on the department instructional Linux machines. If that is not the case, please talk to the course staff.

Hints

The download that the user gets is sometimes called the "binary release" because it contains a pre-compiled, binary version of your product; the download that the developer gets is sometimes called the "source release" because it contains source code. But those terms are not appropriate for all software. For simplicity, we recommend that you create just one release that contains all the information that might be desired by either a user or a developer.

You can and should reuse the information from previous assignments. For example, part of your user documentation might come from your requirements and UI documents, and part of your developer documentation might come from your design documents. (Some of the information might be irrelevant to users or might need to be presented in a slightly different way; a proposal serves different purposes than product documentation.) We do not want you to maintain two parallel versions of information; any future revisions of documents can refer to your documentation where appropriate. In other words, every relevant piece of information should appear in your repository, but only once, and in a place that is easy for a user or developer to find.

If some details of (for example) your UI are not yet determined, you can leave those out; there is no sense in creating a polished document about things that are likely to change. But many aspects of your project should be settled by now, and you should document all of those. The documentation should reflect the progress your team has made so far.

The user/developer directions should be written so that a careful (but not telepathic) user/developer can follow them.

The most important thing is that your directions accurately match what the user must actually do. However, part of your grade will assess the simplicity of the instructions — the number and complexity of commands that a user or developer must use. Ideally, each task (compilation, testing, deploying) can be accomplished using a single command (a "one-step build") that invokes a build tool such as Make, Ant, Maven, SCons, rake, etc.

The staff needs access to your version control repositories, bug trackers, databases, and the like; if the course staff members' normal CSE accounts do not have access, then make a new account that the staff can use to access all of your materials, and tell us the usernames/passwords.

You may want to arrange a "dry run" with the customer beforehand (after doing a flawless one yourself, of course), to ensure that your instructions work.

---

Updated 5/17: Added more explicit information about steps for making a release and the ability to make a private release for testing. Slight re-organization of other material for clarity.