CISC370, Project PO2, Summer 2007:
Programming as a Team

Due: Thursday, 08/02, 11:55pm

Better: Try to be done by Thursday 07/26!

Introduction

This project is designed to get as close as possible to what real world programming is like.

We have a piece of software, the BeatBox, which is "collectively owned" by the entire programming team (i.e. everyone in the class). We are all jointly responsible for making some improvements to this piece of software, and delivering a new release. And, we have a tight schedule: one week.

You will work in pairs (except for one person—since we have an odd number of people in the class, that person will "pair with himself". From now on, when I speak of a pair, that individual counts as a "pair".)

The pairs are different from those for P01—I've just shifted everyone one place to the left in the list. Here are the pairs, and links to the wiki pages for each pair.

Each pair must take the responsibility for two open issues from the Bug Tracking system—one "minor" issue and one "major" issue—and resolve those two issues by 11:55pm, Thursday 08/02/2007

Resolving the issues means making the necessary changes to the code and checking those changes into the repository in a way that is compatible will all the other changes in the repository. If your change breaks some other pair's changes, then both pairs are responsible for working out a fix, and the extent to which you do or do not do this successfully affects the grade of both pairs.

So, it is not enough to just turn in your code—right up to the deadline, you need to be checking on the build to make sure your stuff still works.

Choosing your Issues

Both the minor and major issues are of differing sizes and complexity. The sooner you and your pair choose an issue, the more choice you will have in picking one of an appropriate size for your programming skill.

The minor issues include generating Documentation and Test Cases. They are designed as "warm-ups" to help you get more familiar with the code before you take on a major issue.

The major issues involve making some changes to the code. In many cases, these changes will require some refactoring.

Managing Code Conflicts

Probably the hardest part of this project will be managing the fact that you will be all be working on the same code repository at the same time! (By the way, that's the hardest part of real world coding too!)

This is probably not something you are accustomed to, but it is definitely something you need to get used to if you are going to be involved in large software projects. You are likely to encounter this problem too in CISC475, the "capstone" course of the Computer Science major.

To manage this problem, you must constantly be in communication not only within your pair, but across pairs as well. You will need to make good use of email, the wiki, instant messaging, perhaps even exchanging phone numbers or arranging to meet face to face outside of class.

Required Reading

Chapters 11-15 and Appendix A in Head First Java, 2nd Edition .   But If you are short on time, and want just the "big picture" view, look at these pages:

p. 316, where the BeatBox project is introduced,
p. 418, 419, where some more details are presented
p. 430, where the BeatBox is used to explain serialization
p. 462-464, where BeatBox serialization is explained further
p. 472-473, about the BeatBox "chat" features (networking)
p. 523 with a picture of the "final" BeatBox code

Finally, read through p. 649-658, Appendix A, with a complete listing of the code that you are going to be working with in Project 2.

Of course, as you read through that code, you are likely to see all sorts of stuff you don't understand. It is at that point, that you'll want to go back and read Chapters 11,12,13,14,15 in more detail (indeed, maybe chapters 1-10 as well!).

What you need to do

Get familiar with the code

Log into strauss. Create a subdirectory ~/cisc370/p02, and cd into it. Use svn to check out a copy of the repository:

 svn://svn.acad.ece.udel.edu:13009/usa/pconrad/repos/BeatBox

I have created svn usernames/passwords for you on this SVN repository.  The SVN usernames match your strauss username, and the SVN password is the one from the initPw field listed under "My Grades" in WebCT.

Use ant all to build the code and the documentation.

Then, try running the BeatBoxNew program. You need to do this on a system where you have access to sound—e.g. the Sun Rays, or on a PC. (Running this in an SSH window on strauss will be of no use whatsoever—you'll hear nothing.)

The easiest thing to do is to download the BeatBox.jar file to a PC that has the Java Runtime Environment installed, which most do.

• The BeatBox.jar file is built when you type ant jar and is also available from the distribution directory after you run ant all.

After you download the BeatBox.jar file, you can run it with this command (where Fred is the name you want to be known by in the chat window):

> java -jar BeatBox.jar Fred

To use the chat features, you also need to run an instance of the MusicServer. For now, that has to be on the same machine as the client, which is kind of annoying---this makes the chat features pretty useless except for testing (i.e. the same person running two instances of the client on the same machine). Fixing that is one of the open tickets that you might choose to work on.

Initialize your Mantis Account

I've installed a bug tracking system called "Mantis" that we will be using as part of project P02.    You will need to create an account on this system.

You will receive an email with a link that allows you to set up your initial password.    When you get this email, please respond and create your account.     I've set up the system with https so that passwords are encrypted as they go over the network.

Login to Mantis and browse through the issue reports

Once your account is set up, you can login at the following address:

https://pconrad.safesecureweb.com/mantis

There is also a link to this page called "Mantis" from the main CISC370 web pages and from the left menu of the wiki page.

Once you've created your account, begin looking at the bug reports under the BeatBox project---that is what we'll be working on for project P02. You and your pair need to choose, between the two of you:

• one minor issue (a testing or documentation issue)
• one major issue (a new feature)

Once you've chosen two issues, for purposes of the Mantis system assign one of them to one member of your pair, and the other to the other member of your pair.

You do this in the Mantis bug tracking system, and on the wiki page

The Mantis bug tracking system is accessible at https://pconrad.safesecureweb.com/mantis (and from the Mantis link on the main course web page and main Wiki page). Log in, and click on "view issues". Choose the issue you want to work on, and find near the bottom left, the place where you can click on "Assign to Myself".

Then, go to the wiki page for your pair (links to those are at the top of the file, and accessible from the Wiki page [07J_P02]. Update that wiki page information about your choices. Refer to the issue numbers from Mantis, and also include a brief description of the tickets you and your partner are taking on.

Remember you and your pair-partner are jointly reponsible for both tickets—assigning one of you the minor ticket, and the other one the major ticket is just a bookkeeping detail (since Mantis does not allow a ticket to be assigned to more than one person.)

While programming, use OOP and TDD principles where they can be applied

By now, you know what that means, but here are a few reminders:

• Make classes that will help you solve the problem, and write the tests for those classes first.
• When you discover you need a new method, write the test for the method, then a stub for the method, and finally, implement the method.
• Test every time you compile.

However, this will present a challenge, because the HFJ code was not developed with this approach in mind.

You may need to refactor the HFJ code for the TDD approach to be applicable

You'll see that the HFJ code was not developed using a TDD approach, and thus may need to be retrofitted. In fact, the code really needs a major refactoring into a more MVC type of architecture—that is, a Model View Controller architecture—to be amenable to test development.

I've started this process—that is what the files BeatBoxNew.java, Tune.java, PercussionInstrument.java, and PercussionInstrumentBank.java are. In particular, I've factored out three objects from the program that represents objects that have nothing to do with the Swing UI (User Interface). There may be other aspects of the program that can and should be factored out. That is something you'll need to negotiate, though, with all the other members of the programming team.

You also need to follow the deployment model from H03

That is to say,

• You need to put all of your code into a package with an appropriate name—one that starts with org.phillconrad.hfj2 .BeatBox
• When you check code out of the svn repository, you'll have a directories called src and html, and a build.xml file that creates subdirectories called build, temp, and javadoc etc as needed.
• There is an index.html file in the html subdirectory, similar to the one we used in H03.
• You'll need to make sure that you can use the ant dist target to deploy documentation and a distribution file for your project.

I've also started this process for you, so it should be fairly easier to continue it—in fact, it is the "path of least resistance." I just want to make sure that you know, though, that this way of working is a requirement of the project.

Make your changes first in a local copy, and test them

You'll do an svn co of the repository code into a working copy, and make and test your changes there.

Then, svn up, and test again!

You can't commit your changes without doing an svn up first to be sure that you are committing from the latest version. But, when you svn up, you may find that your changes no longer work! That is, someone else may have committed code that is not compatible with your changes. Now, the real fun begins!

If you can adjust your code to get it to work, then great. If not, you may have to do some negotiating.

Once you've svn up'ed and everything works, commit your changes.

When you've committed your changes, you are done.

Or are you?

Well, not really.

There is collective ownership of the code, but there is also this notion that once you've been responsible for a ticket in a certain part of the code, there is a bit of an expectation that you'll continue to take responsibility for changes that impact that part of the code.

So, once you commit working code for your ticket, you may be done with P02, but there will be a P03 grade that will depend on how well you manage the ongoing support of the changes you made in P02. This includes items such as updating documentation, fixing bugs, working out unanticipated feature interactions.

Finishing and Submitting

There is nothing to submit on WebCT for this project. All you need to do is make sure that

• your changes are committed to the SVN repository
• that you've updated your ticket in the Mantis Bug Tracking system with the SVN version number where you committed your changes and they worked
• that, after resolving the issues in both of your tickets, that you change their status to "resolved".
• that your wiki page linked to from [07J_P02] is up-to-date with a brief description of the fact that you've finished those items, and any relevant notes about problems you encountered and how you overcame them.

Grading Rubric (200 pts total)