Zero-Feature Release Milestone (ZFR)

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.

Product webpage

Your submission will consist of a single URL — the webpage for your product. (This should be linked to from your development webpage.) The webpage should include information about your product, including how to obtain the current release. If your project is itself a website, then the current release is likely to be a live installation. We don't care about the format, as long as it is clear how a user can install (if necessary) and use your software, and it is clear how a developer can begin to work on it (often via a link back to the development webpage, though sometimes you only need one webpage to serve both purposes). If your project includes an Android application, be sure that the app is available for download and can be installed. This will allow the staff to install it on an emulator or another device to ensure that the app fulfills the ZFR requirements.

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.

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. (More information below.)

Don't forget to include a plain-text README file or an HTML 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.
  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 a user obtains and install the software. Your instructions need to be both complete and foolproof. Indicate all steps (if any) that a user must take to install your system on each relevant platform. Assume a user on a departmental Linux home VM, although you may additionally provide instructions for other platforms (the departmental Unix servers or Windows machine, a non-department machine, etc.). Assume the user is a CSE undergraduate who knows nothing about your platform and toolset.

  Your project may have prerequisites (e.g., tools, libraries, emulators, third-party applications, etc.). Your instructions should list all prerequisites and indicate how to install and configure them. If a prerequisite's installation instructions are clear and complete, you may link to the relevant part (don't just link to the prerequisite's homepage and expect the user to figure out installation instructions). If the prerequisite's installation instructions are not clear and complete (e.g., there is information in multiple places, or the user needs to perform additional steps), then you may be better off writing your own installation instructions for the prerequisite.

• how to run/start the software. 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.
• 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, cache, Tatham, Raymond.
  Your list of bugs should ideally be publicly accessible.

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. 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. A CSE undergraduate who knows nothing about your platform and toolset should be able to follow the instructions. The developer documentation should include at least the following information:

• How to obtain the source code, including at a minimum: (a) How to obtain the source code for the latest stable/released version. (b) Where to find the source code repository that you use for development. (Make sure that the course staff has access; we may 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 from the original sources). 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, make this clear to reduce potential confusion.
• 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. You may reference the user documentation to avoid duplication.
• How to set up an automated daily (or more frequent) build and test. For your daily build and test, you may wish to use Hudson, CruiseControl, cron (cronic is a nice script to wrap your cron job), or similar software. Also 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.) By the due date, at least one failing daily test result must be automatically emailed to the team. This obviously requires that at least some tests already exist. We do not require any successful daily tests yet.
• 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: (a) updating revision numbers in your code and documentation; (b) for each kind of release (say, source and binary), creating the zip file, tar file, or other package that a user or developer will download to obtain your product; (c) copying files to your website, so that the new version is visible externally; and (d) sanity-checking that the website and downloadable files are as you wish. For instance, after making a release but before publicizing it, you should check that all the links work, download the software from a fresh account (with none of your own personal customizations) and run its tests, etc.
• Your instructions should make clear how to control the website to which your files are copied. For example, it is recommended that a developer can create a private release (sometimes called a testing release). That way, you can test your software without breaking the publicly-available version. If you want, you can 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, such as a URL.) For the ZFR, your bug tracking system need not have a comprehensive list of every last bug and missing feature. However, for future milestones, if your customer (e.g., the course staff) runs across a problem while using your software, it's better if the bug tracker already 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. Every data structure should have a representation invariant and, preferably, a procedure that tests the rep invariant. Every procedure is required to have at least a one-sentence comment describing what it does — or more if appropriate. Some people write comments to indicate who created or last modified a file, and when; this is not required, because you can tell this from the version control system. Your source code will be graded based on whether it demonstrates the following attributes: (a) work and effort, (b) clearly and elegantly designed, making use of design patterns as appropriate, and (c) documented (both at a high and a low level of detail).

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

Binary release vs. source release

There are some good reasons to make a separate binary release, notably size and simplicity. The binary release, lacking source code and tests, downloads faster and takes less space on the user's computer. It prevents confusion, since users might wonder what all that extra stuff is for. It also prevents temptation, since users might assume they need to recomile when they really don't. Because making separate binary and source releases causes extra work for the development team, we do not require it in CSE 403.

Finally, some open-source projects dispense with a source release entirely, and just publicize a URL to their version control system. That is not always appropriate, and we do not permit it in CSE 403.

Hints

The staff needs access to your version control repositories, bug trackers, databases, and the like. We prefer that you give access to the course staff members' normal CSE and/or Google accounts. If this is impossible, 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.

What information to include

You can and should reuse the information from previous milestones. 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 design/developer documents can refer to your user 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, and should be updated with every future release.

Be brief! There is a lot of information to convey, but if you carefully organize your work (and if you have designed simple processes, both for users and developers), then your documents do not have to be long. In fact, a well-written brief document can convey more than a lengthy one.

Write your documentation to be useful to a user or developer. Do not add details, or put them in some particular order or format, just to satisfy some checklist that you imagine that the TAs have. The most important thing is that your system have a professional feel (modulo expected incompleteness at intermediate stages of the process, of course!). In other words, write your documentation from the mindset of a software engineer, not a student.

User/developer directions

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.