Lecture 5, Groupware

Part of the notes for 22C:196:002 (CS:4908:0002)
by Douglas W. Jones
THE UNIVERSITY OF IOWA Department of Computer Science

Subversion

A compiler development project is a large effort, typically more than one person would want to do. As a result, we are naturally interested in tools to help a group of cooperating programmers work together on a large project. Over the years, two dominant approaches to group development have emerged, both of which classify broadly as version control systems. Any version control system will keep a record of previous versions of a program and allow you to roll back if you want to see earlier versiions, and all of them maintain some kind of change log.

One class of version control system allows individual team members to check out files, work on them, and then check in their changes. If one team member has a file checked out, the other team member must wait until it is checked in before checking it out. In effect, this approach enforces mutual exclusion locks on each file -- locks that are held by programmers.

The second approach eliminates mutual exclusion. If two team members happen to check out the same file, they are both allowed to make changes. When a file is checked in, the version control system checks to see if there have been other changes made to that file since it was checked out. If the changes do not lead to conflicts -- for example, if one team member edited lines 10 through 15 while the other team member made changes after line 20, the version control system simply merges their changes. If a conflict is found, for example, both programmers made changes to line 7, then the version control system informs one of the programmers (the one who checked in later) about the conflict, and allows them to resolve it.

Subversion, the tool we will be using, works this way. Subversion is widely used, both from the command line, and from various GUI tools. Subversion is installed on the departmental Linux machines.

To install the basic command-line Subversion tools on a Raspberry Pi, type this shell command:

	apt-get install subversion

Subversion is completely documented on line. The book Version Control with Subversion is available as a single HTML document, as a hyperlinked web site, and as a PDF download. It is not a comfortable starting point for the beginner, but it is an excellent reference.

From the Unix or Linux command line, Subversion is accessible through the svn command. The svn help command lists all of the subsidiary Subversion commands. One of them, used to add a file to the Subversion project, is svn add. To get more information about that command, type svn help add. This works for all of the subsidiary Subversion commands, but again, it is not a good starting point.

Getting started

A Subversion repository has been created for this class at

	https://svn.divms.uiowa.edu/repos/c_196_jones

Yes, it looks like the URL of a password protected web site, but that is only because the Subversion system uses the web's HTTP protocol to upload and download files, and it uses the Apache web server's security mechanisms. Attempting to view this site using a web browser, even if you type in the correct user name and password (your own, since all students in this class have accounts on the departmental servers), you will not see much of interest.

To connect Subversion to this repository, issue the following shell command while in your home directory, with your own user name substituted for the string HAWKID:

	svn checkout --username HAWKID https://svn.divms.uiowa.edu/repos/c_196_jones

This will work without the --username option if you are working on a machine where you have already signed in under your HawkID, for example, if you are connecting to Subversion from a departmental server. If you are on a Raspberry with the default user name, relying entirely on physical security for access control, you need to type it.

On typing this command, Subversion will prompt you for your password. Use your HawkID password. Once authenticated, Subversion will create a new directory in your home directory (assuming that was the current directory) called c_196_jones. That directory will appear to be empty except for a file called README, and, if everyone follows the rules, one file per project, the root directory for that project.

In fact, there is much more there. If you do the ls -a command while in the new directory, you will see a hidden directory called .svn -- this directory holds all of Subversion's information about your project. Among other things, it holds the URL above, so you never need to type in that long command ever again, and it holds your password, so you never need to type that again.

Some Subversion Commands

Here is a quick list of the Subversion commands you will be using regularly. These are more fully documented under the svn help command, and in Version Control with Subversion.

svn add FILENAME
After you have created a new file or directory in your Subversion repository, you can put it under Subversion control with the add command. Everything in the repository got there by being added at some point. Please do not add object files or executables. Try to keep the repository so it only contains the source code of your project, including documentation files and makefiles.

svn update
The update command, with no argument, will get you the current version of every file in the current directory -- that directory must, of course, be part of a Subversion repository.

As a rule, do svn update in your project's subdirectory before you try to use make to test your code.

As a rule, don't svn update the root directory for our project, c_196_jones. It will take lots of time and disk space because you will get copies of every project in the class, and that will tempt you to read code by people outside your project. Note that all Subversion actions are logged!

svn update FILENAME
The update command, with a file or directory name as an argument, will get you the current version of that file or directory from the repository. Before editing any file in the archive, do an svn update on that file so you will be editing the current version. If you've just done a parameterless update of the directory holding the file, you have the current version, but if you've been working for a while, you may not have the current version and you should update.

svn commit
The commit command, with no arguments, commits all changes to the current directory in the Subversion repository. When you commit, Subversion will open an editing session allowing you to give an explanation of the change you made in the log entry for the commit. Conventionally, change log messages should be short, things like "fixed bug in numeric conversion" or "added support for negative numbers". Your user ID and a time stamp are automatically included in the log message.

Note: The editing session for the log message will be opened using the editor specified by the SVN_EDITOR shell variable. This shell variable is traditionally set in the shell's .rc file (on the departmental Linux system, this will be .tcshrc. On a Raspberry, .bashrc). If you don't set this variable, Subversion may use an editor you don't know.

svn commit FILENAME Just commit the changes to the indicated file. If you've just edited one file, this is the most common form of commit.

svn mkdir
svn mv
svn cp
svn rm
The normal Unix/Linux mkdir, mv and cp commands still work in directories under Subversion, but they do not inform Subversion of the changes they made. Therefore, if the files you are working with are files you want to be in the repository, you must use the Subversion versions of these commands so that the repository is changed to mirror your local changes. Note that the actual changes may be deferred until you do svn commit to the directory that these have changed.

In summary, the normal minimum subversion session will go something like this, with PROJECT changed to be the name of your project:

        cd c_196_jones/PROJECT
        svn update
        -- edit file FFF
        svn commit FFF

Good Subversion Manners

Commit your changes! The most common cause of trouble in a project comes when participants don't commit their changes frequently enough. If two people are working on related parts of a project and one of them does not commit changes, the other one will never benefit from those changes. The longer you wait between commits, the more likely your changes will be to conflict with the changes made by someone else.

Test before you commit! If you're changing source code, at the very least, get it syntactically correct. Once a particular source file reaches the point where it can be compiled, don't commit broken versions of that code. In projects with makefiles, run make before you commit.

Acknowledge bugs! Keeping a file in the Subversion archive called something like BUGS or TODO is a good idea. When you notice something is missing and needs to be added or broken and needs to be fixed, add a note in that file. Keep that file up to date, delete bug notices when they are fixed, and delete desired features notes when those features are added.

Be polite! Ask before you make major changes to code someone else wrote. Discuss alternatives.

Take responsibility! Be accurate but concise in your log messages. The project is a group responsibility. If you find something that you can fix, fix it, don't delay to get permission. Time spent passing blame around is time wasted.

Keep the Subversion repository clean! Don't let Subversion know about object files and executables. This is one good reason to make sure your makefile includes support for make clean.