[Orborde]

After a year off of FIRST, I'm back, now as a mentor at Purdue University (assigned to team 1747) and I'm pretty enthusiastic. Given how disorganized software team tends to get, I wrote up the following thoughts on how to keep the software team organized and in good communication with the rest of the team:

Proposed Software Team Organization Stuff

As a programmer on 1024 for two years, I ran into a lot of problems keeping the software team updated to the current robot state. Also, code got disorganized, misplaced, impossible to locate when someone needed it, resulting in someone with only a dim idea what they're doing trying to hack something together 5 minutes before a regional starts, and general chaos. The following is a proposal to keep things organized and in the realm of engineering rather than randomness.

1. Set up a source code repository (probably using Subversion) on either its own server at the school or on one of my own machines in my dorm room (which have globally visible IP addresses).
- Each of the programmers will have a username on this system. There will also be a "general team" account for the people that will inevitably want to change things around on the robot without telling anyone. The repository may be configured to automatically email the entire programming team whenever a commit is made from the "general" account.

2. The revision control repository will be automatically mirrored and backed up nightly to several different places, including:
- A backup server somewhere (possibly the mentor's laptop, if nothing else)
- The mentor's school home drive
- A full copy of the repository, along with an archive of the latest trunk version and other branches, will be put up every night at a certain web site (likely the mentor's or the lead programmer's), and the address made known to EVERYONE. This will ensure that, as long as we can get internet somewhere, we can get our current code.

3. Print up "information from the programming team" flyers and post them conspicuously around the build zone. These flyers may include:
- "General commit" username, password, and the hostname of the repository.
- Since we understand that the non-programming people may be less than enthusiastic about messing with the revision control system, there will also be a "programming team official contact" email (either that of the programming mentor or of the lead programmer).
- Programming team cell numbers
- There will be a notice in VERY VERY LARGE LETTERS that ALL CHANGES TO THE WIRING OF THE ROBOT MUST BE COMMUNICATED TO THE PROGRAMMING TEAM SOMEHOW; a simple email to one of the "contact" addresses, at the very least.
- The address of the web site containing the globally-visible current source tree archives mentioned above, along with a description of what to do with it.

4. The interface to the robot hardware will be abstracted through a header file and DOCUMENTED. The "interface" header file will contain macros mapping things like LEFT_TREAD to pwm01 (for example), along with an explanation of how to use it (such as 254=forward, etc.). There will be NO direct access of any variables (such as p1x) ANYWHERE in the user code.
- The interface information will be printed up (possibly in a spreadsheet) and placed next to #3, with a warning in very large letters written on it that anyone who deviates from the listed interface without telling the software team will, in polite terms, be shot.

5. The software team will meet regularly with the heads of the other technical teams to maintain good communication.

The above are the primary goals I would like to see fulfilled in the organization of the software team. Some other ideas that may or may not come to fruition:

6. Automate, automate, automate. The mentor (and, with luck, the lead programmer) has enough UNIX capability to implement many scripts to keep things in order in the code tree. Some things that could be done automatically are:
- Scan through every commit to make sure that the "no direct hardware access" requirement in #4 is not violated. If it is, the system will allow the commit but send an email to the person who made the commit pointing it out. If it is made from the "general commit" account, an email will be sent to the programmer elected to fix these sorts of mishaps.
- Run a nightly build of the source tree (as many real software houses do) and email someone if it fails.
- Write "testbed" C programs that pull in chunks of the source tree for unit testing against various inputs and report the results.
- (This one borders on fascism) Keep file-by-file reports of "lines of comments" vs. "lines of code", and have the mentor look into files that have low comment-to-code ratios.
- Any other clever automated testing or checking we can think of. Obviously, we don't have much need for memory leaktesting; what else?

I decided I'd run this by you folks here at CD before inflicting it on the students. So what do y'all think? Is this overkill for a FIRST project? Has anyone else tried any of the things I've mentioned on their own teams? Have any suggestions?

Thanks,
-William