Zero-Feature Release


Due: Friday, May 01, 2015, 11:00pm

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 entire submission will consist of a single URL—the webpage for your product. This is different from, but should be linked from, your development webpage.

The product 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). If your project includes an Android application, be sure that the app is available for download and installable. This will allow the staff to install it on an emulator or a new device to ensure that the app fulfills the ZFR requirements.

All information on your webpage must appear in your version control repository. 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, a Markdown README.md, 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:

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 Markdown. 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 without confusion or delay. The developer documentation should include at least the following information:

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

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.

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 recompile 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 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 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.