Due: product webpage by Monday, May 2
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—submitted via the course dropbox. This is different from, and 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, 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 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.
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 a user obtains 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. Your instructions need to be both complete and foolproof. Indicate all steps that a user must take to install your system, on each relevant platform. Assume a user on a departmental Linux home VM, though you may additionally provide instructions for other platforms (the departmental Unix servers, 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 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: Oracle, 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 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.
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:
How to obtain the source code, including at a minimum:
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, 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. 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, we strongly recommand Travis CI. It has good integration with GitHub and it's easy to set up. If you don't like it, you may try Jenkins, 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.) 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. 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:
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.
It is permissible, but not required, 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, 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 this and future assignments, if your customer (i.e., 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. 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 permitted but 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:
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.
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.
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.
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.
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.