18-649 Project F.A.Q

Last updated January 12, 2009

*Please submit all project-related questions to {email} -- thanks!

Online File Submissions (for projects)

Use the AFS space for handing in assignments:

Starting with project 2, you will download the portfolio template and build on it throughout the semester.

It is important that you follow these guidelines because the course staff may use automated scripts to parse your portfolio directories and run your elevator code.  If you do not follow these guidelines, you may have points deducted from your score.

Late submissions:

Technical glitches can (and probably will) occur during the course of the semester.  We will try to be reasonable, but it is your responsibility to submit your work on time.  You should plan ahead enough so that you can turn your work in comfortably before the deadline.  Report any problems with the submission as soon as you are aware of them.  Most technical issues, especially those avoidable with reasonable planning, will not result in an extension of the deadline.

Late submissions will be treated in accordance with the course late policy.  Within each group's folder, there is an “ontime” and “late” folder. You should submit your solutions in the “ontime” folder, which will be locked by the TAs after the assignment is due. The “late” folder is provided in case you wish to submit an assignment after the “ontime” directory has been locked.

Late penalties increase over time.  The late penalty assessed for your handin will be determined by a combination file timestamps and the time when you send the second email notifying the course staff that your late submission is ready (see below). If you overwrite or otherwise update a file, the latest timestamp displayed on any file will be treated as the hand-in date and time for the entire assignment. 

If you wish to submit your project late, you must send two emails. 

If you fail to follow these steps and properly notify the course staff, then whatever grading the TAs do for your project will stand, regardless of what you may later submit.


Process Correctness vs. Good Design

Why do we grade on process instead of design?

On any given project, the primary grading criteria will be whether you followed the design process thoroughly and correctly.  We grade on process because this provides objective grading criteria.  However, it is important to remember that good design does not guarantee good process!  You could follow the process requirements to the letter and still produce a design that omits significant functional or safety aspects of the elevator.

Why does good design matter if you only grade on process correctness?

In addition to the process requirements, you must have a working elevator at the midterm project and at the final project.  A working elevator passes acceptance tests.  That is, it delivers all passengers and doesn't trigger the emergency break.  The quality of your design is what will determine whether or not your elevator can pass these tests.  That is why the design matters!

Why do I have to follow the process?  Why can't I just get into writing the code?

This project is NOT about writing code.  It's not even really about elevators.  The elevator is just a convenient example.  It is about learning to follow a software process and to use that software process to produce a reliable distributed system that meets high level (customer) requirements.  If you learn the right lessons, you will see that the code is probably the least important part of the design, and that the code will practically write itself once you have completed the other parts of the design.

Also, because one of the process requirements is that the code must trace to the rest of the design, you will lose significant points if the code you write doesn't match up with your design, even if you do somehow manage to pass acceptance tests.

What if I don't believe you?  Can I just scrape by, doing the minimum amount of work to meet the process requirements?  Then when we get to the code projects, I can hack together a working elevator.

Every semester, there are a couple of teams that take this approach.  These are some of the consequences we have observed:
Wait!  I don't know anything about design or software process!  You're making this sound impossible!

This project and course is aimed to teach you software process, not expect you to already be a master designer.  Here are some tips to help you:

Simulator Debugging Tips

Here are a few ideas for things to look at when you are having trouble getting your design up and running in simulation.  You can also consult the simulator debugging page for more specific tools available in the simulator to help you debug your design.


Bug Handling Policy

We make every effort to provide you with an accurate, reasonably bug-free simulator.  However, as you will find out, all software has bugs.  This section describes procedures you should follow in reporting them and how to handle simulator bugs with respect to project submissions.

How do I make a bug report?

If you find a bug in the simulator, please notify us as soon as possible.  Include as much detail as you can, such as:
Be as detailed as possible in your bug report.  For example, "Line X in file Y is causing this specific problem.  Here is my code and a specific test case that reproduces the problem."  A detailed bug report is much more likely to get resolved quickly.  A generic bug report like "I can't make Module X work, so there must be a problem with the simulator." will probably just result in us asking you to come to office hours for clarification.

You are encouraged to debug the simulation yourself (to the extent that you can) and determine the source of the problem.  If you believe you have found a fix, please submit the details of the fix along with the above information.

What happens when bugs in the simulator affect my ability to hand in code that compiles and runs correctly?

Note that, ultimately, you are responsible for the correct function of your elevator simulation.  We will gladly work with you to identify and remove bugs from the simulation, but do not try to "game the system" by waiting until the last minute to report a bug to us.  It is in your best interest to report bugs to us as soon as possible.

Because of the possibility that there will be bugs in the simulator, we will likely be releasing newer versions of the code on an ongoing basis.  Most bug fixes and improvements will likely not affect the compatibility of your code.  However, it is possible that a change will require you to modify your code to maintain compatibility.  Therefore, we have established the following policies related to bugs in the simulator.  Note that you can always visit the download page for a history of code releases and brief description of the changes in each release.

Simulator releases at the beginning of a project

In general, we will try to wait to release a new version until the beginning of the next project.  For versions released along with the new project, your group will be responsible for making any necessary change to make their code function correctly with the latest version of the simulator.

Simulator releases between projects

If we (or one of the project groups) identifies a serious bug in the simulator, we may need to release a fix while one of the projects is in progress.  In that case:

For releases more than 48 hours before the deadline: 
For releases within 48 hours of the deadline: 


Useful Tools

Here are some recommendations and links for tools that you may find useful.  Please note that we do not support ANY of these tools or programs ourselves.  If you have trouble with a tool, ask a teammate or classmate.  If you are having trouble with department resources (e.g. AFS) on department supported machines, you can also send mail to gripe@ece.cmu.edu

AFS

Most on-campus Windows PCs already have your personal AFS space mounted as a drive letter.  Most on-campus linux machines use your AFS space as your home directory.  We recommend that you use the AFS space for your project development because it is easy to move from computer to computer and share code with your teammates. 

A note on privacy:
You should use the Private folder for your code.  Please read the AFS ece wiki page for information on how to add permissions that will allow your teammates to view your code.  DO NOT put your code in your Public or home directories.  Anyone with AFS access, including people from other teams, can view these directories.

You can use the OpenAFS client to access the AFS space in windows.  Sometimes this can be unreliable.  Another simple way to transfer files to AFS space is the use the 'scp' command (linux) or WinSCP (Windows) to transfer files to one of the color cluster machines like black.ece.cmu.edu (these machines use AFS for your home directory by default).

Version Control

Subversion (SVN) is a version control system that is already installed and configured on most of the campus machines.  Once you create a repository (in your private AFS space), you can check out a copy of the code, modify it, and submit your changes.  The version control system keeps track of all changes made so you can roll back or access earlier versions.  It also helps you resolve conflicts if more than one person has modified the same file.  SVN has a significant learning curve, but if you take the time to figure it out, it can provide significant benefits in helping you keep your code synchronized and up-to-date.

DO NOT put your code on GitHub or Google Code. Anyone, including people from other teams, can view code hosted on these services. This is NOT ALLOWED by course policy.

Note:  SVN is useful for maintaining code files, but the .svn control directories can significantly to the size of your portfolio directories.  Because course AFS space is limited, if you use SVN (or another version control system), you must turn in a clean copy created using the export feature.  You may be penalized if your submission includes the version control directories.

Here are a few tips if you keep your SVN repository on an AFS directory:

Text editors

The cluster machines have vi and emacs / Xemacs, which are useful text editors that can be run on the cluster machines in a terminal or over a forwarded X11 session.  If you have your AFS directories mapped to a local drive letter, you can also used any locally installed editor. Here are a few suggestions for Windows users:

Even if you use netbeans for Java, you may find it useful to have a plain text editor available for writing configuration files and reading simulator output (stats) files.

Java

All the project code development is done with Java.  In order to receive credit, your code and tests must compile and run on the games cluster machines (e.g. chess.lab.ece.cmu.local) as described in the simulation overview.  However, you may prefer to do some of your own development and testing on a local machine.  This may also be helpful if you are somewhere with a slow, unreliable, or nonexistent internet connection or if the cluster is temporarily unavailable.  Here are some links and tips to get you started.

Here is a short tutorial on how to get the project code into Netbeans.  These steps were tested on version 6.7.1 (the latest version as of January 2010), but earlier versions had slightly different library handling capabilities, so you may have to adjust these instructions slightly for those versions:

  1. Create a new project.  Choose "Java" from the categories and "Java Application" for the type and click Next.  Choose a location and uncheck the "create main class" option.
  2. Navigate to the project directory and find the 'src' directory.  Copy the contents of the 'code' directory from the elevator simulator codebase into the 'src' folder (which should be empty if you created the project correctly).  After the copy, you should see the simulator classes appear in the project navigator in Netbeans.  You may need to expand the "src" folder to see them.
  3. Right click on the project name in the navigator pane and select 'properties'.  Go to "Run" and set the main class to 'simulator.framework.Elevator'.  Note that you can also set command line arguments here, and specify the working directory (useful if you want to use a folder which contains your test files).  The default working directory is the project directory.
Right away, you'll notice that the project fails to compile.  This is because the simulator download only contains class files (not source files) for the elevator control objects.  Eventually, you will include these objects yourself.  You can avoid this headache by just using the makefile from the commandline for the early projects.  But if you want to go through the trouble, you can get Netbeans to see the class files them by executing the following steps:
  1. In the netbeans project folder (where you see the folders "src" and "nbproject", create a folder called "lib".
  2. In the "lib" folder, create a subdirectory called "simulator".  In "simulator", create a subdirectory called "elevatorcontrol".  This creates a package hierarchy that mimics the one in the project framework.
  3. Copy all the class files from the code/simulator/elevatorcontrol/ directory (in the files you downloaded) to this new elevatorcontrol folder.
  4. In the Projects overview pane, right-click on the "Libraries" entry and choose "Add JAR/Folder".  Navigate to the "lib" folder you just created and add it.
  5. If you followed these directions correctly, you should be able to compile and run the project.  As you create your own source files for the controllers, you will want to remove them from the "lib" directory to avoid confusion.
A few final tips:

Note:  When you submit code to be graded, you must submit the source code only in accordance with the project portfolio guidelines.  You may NOT submit your Netbeans project.  It's up to you to understand which parts of the project are the project source and which parts are the related to the Netbeans IDE.  If you feel you cannot do this, then you should do your development using the cluster machines and a basic text editor.


HTML / Webpage Editing

There are numerous HTML editing tools available, and you are free to use whatever tool you like. 

Seamonkey Tips

Image Editing Tools

There are several choices for creating and editing UML diagrams.  You will find it easiest if you pick a tool that is available to all members of your team and use that tool exclusively.  This makes it easier to edit the source files for your images later in the project.  Here are a few suggestions
The example sequence diagrams in the portfolio template were generated Dia.  You are not required to use Dia.  Visio is available in the campus labs and there are many other drawing programs out there.  Our only criteria is that you produce legible diagrams in your portfolio and in your presentations (although these two types of documents have different requirements relating to font size).  Regardless of the eccentricities of Dia or any other tool, you are ultimately responsible for finding a tool and making it work to produce the required figures.

A few notes on Dia

These notes were generated based on our experience with version 0.97 for Windows, but will likely be applicable to other platforms and versions as well.

There are basically two approaches to making figures in Dia:
  1. Using built-in UML primitives. 
  2. Use the native drawing elements (lines, boxes, etc)
Other tips:

Back to Course home page