CSCI E-168

This is now final, though the list of “features” (item 8) will grow a bit. Stay tuned.

The Final Project (hereafter, FP) will be a web application designed and implemented by you. The basic idea is that you come up with a project of similar complexity to Assignments 4 and 5, with some additional features.

Proposal due date: Nov. 19. Proposals submitted earlier will be reviewed and approved earlier.

Final project due date: Dec. 17. Note: This due date is absolutely final, owing to Extension rules regarding examinations and final projects.

The requirements are as follows:

1. You must write a FP Proposal and have it approved by your TA. (Approval means that you have an e-mail from the TA in which the TA writes: “I approve.” Your TA may tell you that the project is approved only if you make some changes in the proposal; if so, make the changes, and get that final approval!)The FP proposal talks briefly about what the application will do, what its models, controllers, and views are like, and what additional “features” you will implement — more on features below.
2. Due date for the FP proposal: The due date for the final project proposal is: Nov. 19. If you can get your proposal in sooner, the staff will make every effort to provide feedback sooner rather than later. One thing you might consider is to give your TA a brief “pre-proposal” that provides in a paragraph some idea of what you intend to do before you write the full proposal; by this means, you might be able to get a bit of early tuning.
3. The FP proposal must be a document written in plain English (i.e., not just an e-mail, and not a PowerPoint or KeyNote slide deck; it must be a PDF, an RTF file, a TXT document, or a ZIP of an HTML page). The audience of the FP proposal is an informed developer who needs to know the application’s scope and (high-level) how it will work. You should include enough information so that the developer would be able to evaluate whether or not he or she would want to implement the project. It is not a specification; it is a proposal. Please, do not provide a cover page, table of contents, list of figures, etc., etc.: Stick to plain sentences and paragraphs; lists can be useful for things like your descriptions of models and use cases (see below). How long should it be? My advice is to keep it as short (but clear) as you can; your TA will be able to tell you quickly if there is not enough detail, and then you will have time to resubmit.
4. The FP should accomplish something. It should allow a user (or users) to get something non-trivial done. You should begin your FP proposal with a description of what the application accomplishes, and why you think anyone would be interested in it. Your FP proposal should “argue” a bit for the usefulness of the FP. If you like, include real-world data on who would benefit from the application, perhaps in terms of getting its task done cheaper, faster, or better. In the past, some of the best final projects have been: (a) a tool to help the developer with a hobby or other topic about which the developer is passionate; (b) a clone of part of an existing application (if you want to clone an existing application, there should be some kind of significant twist that differentiates your project); (c) something that would be of use to a family member; (d) something that would be useful at work; (e) an application that “mashes up” two or more web-based third-party APIs (e.g., Amazon’s or eBay’s services to provide information about products). One thing we haven’t seen much of is genuinely interesting games.
5. Models: Your FP must have a list of Models that is of similar complexity to Assignment 4/5; i.e., five (or so) or more database tables, and relationships amongst the models. We expect you to use at least one has_many :through or, possibly, a pair of habtm relationships (as you will recall, John prefers has_many :through and hasn’t said much about habtm ["has and belongs to many"], but you can pick it up easily from AWDR). Models must define sufficient validations for the application to work properly (e.g., there should be no surprises because, say, two users have the same login name, if your application expects users to be unique). When you describe the models in the FP proposal, you NEED NOT include a diagram; you can simply list the models, what they represent, and their attributes, associations, and validations. The list should be easy to read. You do not need to list exhaustively all of the attributes — but we do need to hear about all of attributes that are functional.
6. Use cases: Your FP must implement several use cases that exercise the models for one or more types of users. In the proposal and write-up, we like a list of sentences of the form “The user will be able to X.” For examples, see the requirements for last year’s MetricsMine application (http://e168f08.plugh.org/assignments/assignment-3-2/), or for the previous year’s ChildCare Co-Op (http://e168f07.plugh.org/2007/10/21/assignments-4-5-and-6-overview/). It can also be helpful to provide a user story or scenario (again, see MM or CCC). Your TA may well ask for more or less detail on this when reviewing your proposal.It will count negatively against your grade if there are models that are not exercised by the implementations of the use cases, or are exercised trivially. In your FP proposal, you must define the user (or users) carefully, and explain which use cases apply to which users. In large part this is where your FP proposal will talk about controllers. NOTE: The use cases play a special part in the FP Write-up (see below).
7. Pages: You should itemize the most important pages and explain how the user experience in the use cases flows through those pages. In large part, this is where the FP proposal will talk about actions and views.
8. Two Features: In addition to implementing models, controllers, and views, you must leverage two of the following additional features of Rails or plugins (depending on feedback from you, we may add to this list):
   1. E-mail (counts as only half a feature, unless the application makes significant use of e-mail). Send e-mail; but, more importantly for the e-mail feature, the e-mail must be functional to the app. In other words, it might notify users of a change of state in the application, and provide links that, when clicked, change the state of the application. In other words, merely sending notifications is not enough. (And e-mail confirmations sent by restful_authentication or other plugins is not enough.) You might also consider receiving e-mail. These topics are covered in AWDR.
   2. User management (counts as half): Adapt the login / registration code to use the Clearance Gem (http://github.com/thoughtbot/clearance).
   3. Ajax: Ajaxify as much as seems appropriate. Using Ajax on one or two pages will result in very little credit. Creative, dynamic use of Ajax will be reward, as well as systematic and consistent use of Ajax throughout the application. Ajax is covered in AWDR.
   4. REST. Provide a REST interface for at least one of the models. Ideally, you will implement nested resources. If you expose resources through REST, you must provide a sample client. Your best bet for a client is to write a simple application using ActiveResource. . . . covered in AWDR.
   5. Feeds: Expose an RSS or Atom feed with updates regarding the state of some aspect of your application. To get started: http://intertwingly.net/blog/2008/10/14/Rails-AtomFeedHelper-just-got-better
   6. Asynchronous jobs: Manage tasks through Workling (http://playtype.net/past/2008/10/2/workling_version_03_released/) or something similar.
   7. Uploading. Try paperclip: http://www.thoughtbot.com/projects/paperclip/; AWDR also provides some guidance on supporting uploads in Rails.
   8. Time zone handling. See http://mad.ly/2008/04/09/rails-21-time-zone-support-an-overview/
   9. Internationalization or Localization: Provide a means to present your application in another language. THis can be a big topic: Discuss with your TA if you want to try it.
   10. Testing: Provide a complete test suite. This may count as two features. A serious attempt at this feature would require learning about rcov, possibly mock objects, and possibly an alternative (to RUnit) test framework such as Shoulda. If you want to do this, you should already be a testing zealot.
   11. Something else. You must get approval from your grader.
   12. If you propose an application that has significant domain complexity (say, a project with 15 tables and a lot of use cases), we may accept a proposal that specifies only one of the above features.
9. A few notes about the final project packaging, writeup, internal documentation, and implementation (and we will likely have more to say in this department):
   1. The project must have the standard Rails directory organization (i.e., the result of running the “rails” command). We can’t accept assignments that have some kind of home-grown structure. It must be possible to start the server with “script/server” and so forth. Models, controllers, views, and migrations should obey the standard conventions regarding positioning in the directory structure, naming, etc.
   2. The project must run in the environment you set up for Assignment 0! (So Rails 2.3.3, etc.; please, no Rails 2.3.4 or later, or edge Rails!)
   3. Your rakefile must be based on the course Rakefile from the last version of Assignment 4/5. What you submit should be produced by “rake package.”
   4. It must be possible to run all migrations.
   5. The Rakefile for Assignment 4/5 does include a copy of the development database (db/development.sqlite3) in the ZIP. We do want this in case there are issues with your migrations. So don’t delete it prior to packaging.
   6. You must include sample data, i.e., a data migration that sets up sample users, data, etc.
   7. If you are using a gem or plugin that interfaces with a third-party (Amazon, eBay, etc), provide clear instructions on how to set any required components (including how to authenticate, if necessary) on the TA’s system.
   8. The project must be accompanied by a write-up, which is a plain TXT document (called readme.txt or an HTML document (called readme.html) which goes in the root of the project. Keep the formatting as simple as possible. The only reason we allow HTML is to make it a bit easier for you to include screenshots if you so desire.
      • The write-up should cover the same topics as the proposal, but with a greater focus on implementation.
      • As in the proposal, the write-up should include a list of use cases, and a clear explanation of how to exercise each use case; if you want to get credit for what you have done, provide us a way to see what you have done!
      • The “crow”: On occasion, we have received submissions that do something incredibly cool, but for whatever reason the student forgets to tell us about it. Do not forget to “crow” (i.e., brag) about anything that is particular cool or amazing in your project. And don’t forget to tell us how to exercise that cool feature!
      • As promised at the top of this page, we will provide another page with some details about how to create a great writeup. This document will also talk some about internal documentation.