Teaching Software Engineering with Large Team Projects

My first semester teaching undergraduate software engineering didn't go very well. I knew that I wanted to use a single, large class project to better give the students a sense of real software engineering difficulties. But actually implementing this idea was difficult. I chose a boring project, was overwhelmed by project management work, and had a hard time evaluating individual students.

Since then I have developed a course that I think provides students with the experience of working together on a single large project, while also allowing me to keep my sanity. A paper on the way that this large-team approach is used was presented at SIGCSE 2005. Since then, I have expanded the paper to include more experience using the approach, as well as more a more detailed discussion of the individual evaluation technique I use. It was published in the Computer Science Education Journal.

This modified version of Issue Tracker has been tweaked for software development in the style described in the above papers.

• Terms have been specialized. "Module" instead of "Product", "Developer" instead of "Technician", "Difficulty" instead of "Severity". (Note that the old terms may still exist here or there in the system.)
• Private events have been largely removed.
• The default setup of permission sets and groups has been replaced with one that is more suitable. There are now three permissions sets—Developer, Team Leader, and Manager.
• Escalations, internal statuses, and sub groups are not used. (You can safely ignore them.)
• The administration menu is hidden from developer unless they have administrative privileges.
• A "You are logged in as X" message has been added to the left side to help administrators remember the active user subsequent to using the "Switch User" functionality.
• Multiple people can be assigned to an issue.
• Workflow with respect to issues has been modified. Developers can only elevate an issue up to "Waiting for Team Leader". Team leaders can only elevate an issue up to "Waiting for Manager". Only managers can close an issue.
• The status of an issue will change from "New" to "In Progress" when someone is assigned to the issue, and vice versa.
• Managers can assign multiple people to an issue, but developers can only assign themselves.
• Reports can be filtered by category and date.
• Email notifications contain a summary of the changes to the issue.
• More issue editing power has been given to special users. The creator of an issue sets the initial summary, problem description, module, category, due date, difficulty, priority, and modifier. Anyone can assign themselves to an issue, change the module, or change the status. The owner of an issue can also modify the problem description and due date. Finally, a manager can do all of the previous as well as change the owner, and modify the difficulty, priority, and modifier values.
• A new performance report has been added to compute a grade for developers.

To see how the approach was used in previous years, visit the spring 2004 and spring 2005 course webpages. I'm also using the approach this year, and it is also being used elsewhere:

• US Naval Academy: Paul Young and Brian Balazs used a smaller-teams variation on the approach.
• Simon Fraser University: Dana Brand used a more explicitly XP-based variation on the approach.

Greg Wilson and Karen Reid have developed a similar system called DrProject at the University of Toronto. It's based on Trac instead of Issue Tracker.

Download

My course uses the Issue Tracker task management system, modified by myself to better support my course. Almost all of the changes I have made have been packaged up as nice bite-sized patches, and submitted to the Issue Tracker project. As far as I can tell, they have not been merged in yet. (It looks like development has stagnated, and that people are working on Entertrack instead. I have a TA who will be porting my system to EnterTrack this summer.)

You can download the modified version here:

• Latest version: issue-tracker-4.0.4l.tar.gz.
• Previous versions:
  • issue-tracker-4.0.4k.tar.gz.
  • issue-tracker-4.0.4g.tar.gz.
  • issue-tracker-4.0.4f.tar.gz. Patch from e to f.
  • issue-tracker-4.0.4e.tar.gz.

To apply the patch, put it in your issue-tracker directory and run patch -p0 < patch-e-to-f.diff. On Solaris, use gpatch instead of patch. You should be able to unpack the distribution over your existing installation without problems, but I haven't tested this. To be safe, unpack it elsewhere and compare the directories.

Always back up your issue tracker directory before doing an upgrade. To do this, change to the directory above the issue-tracker directory, and run tar cvf - issue-tracker | gzip -9 > issue-tracker.backup.tar.gz.

You should also download the Administrator Guide (mirror here of 0.2 version) to install the software on your web server. I provide detailed instructions for setting things up below.

Installation

You'll need a web server with PHP support, and a MySQL or Postgres database server. You should be able to just follow the step-by-step instructions here, but also see the administrator's guide for more information.

Unpacking the Files

Download the source code to your web server. Unpack it somewhere visible to the web using this command:

zcat issue-tracker-4.0.4?.tar.gz | tar xf -

For example, I put the code in /home/f85/coppit/public_html/csci435/project.

PHP Files Installation

1. You may need to edit .htaccess to comment out one or more lines with the "#" character. I had to because our web server doesn't allow users to set these options. (If you try to point your web browser to the issue tracker, you will get an "Internal Server Error", and then when you check the server error log you'll see the message about PHP options.
2. Edit the file conf/const.php.
   1. Change the _FILES_ constant to the path of the uploads directory. I just use /home/f85/coppit/public_html/csci435/project/issue-tracker/uploads/. Be sure that it ends with a slash.
   2. Change _WEBUSR_ to the userid of the web server. (On our systems it's "wwwrun".)
   3. Change _WEBGRP_ to the group of the web server. (On our systems it's "www".)
3. Copy the file conf/config.php-default to conf/config.php. Open the file to edit it.
   1. Change the $db array values as appropriate. For example, mine says:

      $db = array(
              "type"  =>      "mysql",
              "host"  =>      "zimbo.cs.wm.edu",
              "port"  =>      "",
              "name"  =>      "cs435spring2006issuetracker",
              "user"  =>      "coppit",
              "pass"  =>      "my_password"
      );
      

   2. Change _ADMINEMAIL_ and _EMAIL_ to your email address.
   3. Change _TITLE_ to the web page title. I use "CSci 435/535 Issue Tracker"
   4. Change _COMPANY_ as appropriate. I use "CSci 435/535"
   5. Set $allow_register to TRUE if you want your students to self-register. Note that this would allow strangers to register too, but they won't be able to do much without your permission.
4. Edit css/default.css. Change http://www.cs.wm.edu/~coppit/csci435/project/issue-tracker to point to your installation instead (two locations). Also edit css/default-ns4.css and make a similar change in one location.
5. Optionally, replace themes/default/images/gif/logo.gif and themes/default/images/png/logo.png. If you do, you will need to also update the logo height and width in the template file themes/default/tpl/header.tpl, at the line that says smarty.env.imgs.logo.
6. Ask your systems administrator to set permissions so that the web server can write to key directories. Assuming your userid is myid and the web server group is www, and assuming that your upload directory specified above is uploads:

   chown -R myid:www cache css download logs sessions themes uploads includes/motd
   chmod -R ug+rwX cache css download logs sessions themes uploads includes/motd
   chmod -R o-rwx cache css download logs sessions themes uploads
   

   You may want to bundle this adminstration request with that in the next subsection.

Database Setup

1. Ask your database administrator to create a database for you. I usually ask them for one called something like "cs435spring2006issuetracker". Be sure to get the hostname of the DB server, your username, and your password from them.
2. Set up the database schema. See the adminstrator's guide for details. For example, for our mysql server I do this:

   mysql -h zimbo.cs.wm.edu -u coppit -p cs435spring2006issuetracker < setup/schema.mysql
   

   You should be prompted for the password.
3. Set up the indices:

   mysql -h zimbo.cs.wm.edu -u coppit -p cs435spring2006issuetracker < setup/indexes.sql
   

4. Edit setup/se_data.sql. Find the line that says INSERT INTO users and change the value 'admin' to whatever username you want to be known as. Change the email address in the third field to your email address as well. Don't change the hexadecimal string in the second field.
5. Populate your database with the "software engineering" setup I've provided. (Not the data.sql that the administrator's guide mentions.)

   mysql -h zimbo.cs.wm.edu -u coppit -p cs435spring2006issuetracker < setup/se_data.sql
   

Management

The Administration Panel

1. Log in using the userid you chose above, along with password "demo". Click on the Preferences link at the left, and change the password. Change the email address while you're at it.
2. Click on the Administration link at the top right, then click Message of the Day. This is the message that people see on the login screen. Change it to something like:

   <p><b>Welcome to the Issue Tracker for the Spring 2006 CSci 435/535 class
   project.</b></p>
   
   <p>Watch this space for future messages.</p>
   
   <p>If you find a bug in this system, report it for some bonus points.</p>
   

Adding People To the System

If you configured the system to allow people to self-register, they will automatically be made developers, but will not have any permissions. Below are instructions for manually adding people and setting their permissions.

1. In the Administration page, click New User. Enter their userid, name, and email address. Leave Admin and Employee unchecked.
2. In group management, add each new user to the Developers group using Add/Remove Users.
3. Under permissions, set each user to be either a developer, team leader, or manager.

Adding Modules or Categories

Once a project initial design is complete, it becomes clear what the modules are. Similarly, the number of milestones becomes apparent. Since the system is configured with minimal modules and categories, you will need to add more. The process is basically the same. Here are detailed instructions for adding a new module.

1. In the administration panel, click "New Module".
2. Go to Group Management, then the "Developers" group. Click "Modules".
3. Select the new module on the left, and click "Update Products".

The process is similar for adding categories.

Hiding Issue from Previous Milestones

If an issue is not completed in a milestone, you should create a duplicate issue in the next milestone rather than simply changing the milestone for the issue. The reason is that changing the milestone will alter the performance report for the previous milestone. By copying the issue, you will ensure that the performance score won't change.

One thing that may occur is that old issues from previous milestones may pollute the issues list. In the file conf/config.php is a setting for milestones to date, which includes the current milestone. As your project progresses, add the current milestone to the array. This will filter out issues for previous milestones, and will ensure that the "quick performance report" in the left navigation pane will always reflect the current milestone.

Note that no such filter has been implemented in the "My Owned" and "My Assigned" issues lists.

Students Who Drop the Course

Some students may leave the course prematurely, such as by dropping the course. In this case, the other students must handle the additional load. This is handled automatically by the grading system. Inactive users are treated the same as managersnon-group membersand their work is subtracted from the earnable points.

To make an account inactive, go to the users list in the administration panel and click the checkmark next to their name, making it an ex-mark.

Choosing a Good Project

Choosing a good project can be difficult given the competing requirements. Here are some good qualities of a project:

• It should be large enough for the whole class to work on.
• It should have requirements that build upon each other, so that a functional "base version" can be created in the first milestone, then enhanced in later milestones.
• It should be fun and interesting.
• It should not require specialized domain expertise, such as chemistry knowledge. (If there is, see if this risk can be reduced.)
• There should be no serious "bottlenecks" in development that would cause many people to wait.
• It should not be a past course project.

Examples of projects: a billiards game with 2D and 3D views (fun, but required physics and simulation knowledge), a traffic simulator (fun, not too much specialized knowledge).

Other Notes

We use subversion for version control. If you're using the Berkeley DB implementation of the repository back-end, Unix permissions can be a real hassle. The easiest thing is to rename /usr/bin/svn to /usr/bin/svn.protected, and create a script /usr/bin/svn that reads:

#!/bin/sh

umask 000
/usr/bin/svn.unprotected "$@"

You may run into a problem uploading files larger than 2M. You should definitely test this. Usually it's a problem with the default PHP upload limit. You need to edit the .htaccess file in the issue-tracker directory, adding

php_value upload_max_filesize 15M

This may result in a server error when you try to view the website, if your PHP configuration does not allow this setting to be set in .htaccess. In this case, remove it from the .htaccess file and then contact your system administrator and ask them to edit the web server's /etc/php.ini to set the upload_max_filesize to 15M.

One user has reported problems with logging in, where after entering a username and password, the original login webpage would be displayed again without any error message. The apparent solution was to be sure to have a .htaccess file, even if that file just contains commented-out lines.