CPSC 329 Software Development Fall 2017

CPSC 329 Lab 2: Introduction to Subversive

This handout/tutorial introduces the use of Subversive in developing software. (Installation of the plugin was covered in lab 1.) It is assumed that you have an understanding of the core concepts of version control, SVN terminology, and Eclipse terminology.

Important: Go carefully - make sure you understand the concepts of SVN and what the appropriate action is, and read (and verify) the contents of dialog boxes instead of just clicking ahead on auto-pilot. Version control systems are meant to not forget, which makes fixing problems of incorrect or undesired usage that much more difficult.

Objectives

Successful completion of this lab means that you:

Note that achieving these objectives means that you understand what the steps you are carrying out accomplish and why you would do them - you can nominally complete the lab by just doing all the steps but you will have missed the point.

Collaboration

Work in pairs (and one group of three) to complete this lab. There is no limit on collaboration with others, but you need to make sure that you understand for yourself how (and why) to do things.

Due Date and Deliverables

due Tue Sep 12 at the start of class

One handin per group.

To hand in the lab, create a handin tag as directed and include the names of everyone in your group in the commit comment. The repository logs will be reviewed to determine that you carried out the rest of the lab correctly.


Local Notes

Repository Directory Structure

SVN just manages files; it doesn't impose any particular structure on how things are arranged in the repository - it is up to whoever is managing the repository to define how the repository will be organized. We will be using a fairly standard organization, which is structured as shown:

cs329f17                   (the repository root)
  |
  +-- username              (your repository subdirectory)
       |
       +-- project name     (such as dogdoor)
            |
            +-- trunk       (contains the main path of development)
            +-- branches    (contains branches)
            +-- tags        (contains tags)

This structure will keep the files for each project/assignment separate from the others. trunk will contain a complete copy of all of the files, and will be the master version. branches and tags will contain a separate directory (and copy of the files) for each branch or tag. (More on branches and tags later.)

Usage Conventions

The repository directory for a project will generally have the same name as the Eclipse project holding the working copy. (This is not required, but is helpful for keeping track of things.)

Only Java source code (and other project files) will go into version control - Eclipse-specific elements like .project, .classpath, and .settings will not (since these may need to be different in different environments). (This is just a convention; if you are working on a single computer or everyone in the group has an identical environment, you may choose to put the entire project into the repository.)

Repository Server

The repository for this course is hosted at 172.21.7.83 - use this as the hostname when setting up repository locations.

Note: The repository server is not accessible from off-campus. If you are not on campus, one option is to run VPN; see the "Remote Access" section here for more information. If you have ssh (generally available from a terminal on a Mac or see here from some information about Windows), you can use ssh port forwarding to access the repository. On your local machine, run

  ssh -CNL 9000:172.21.7.83:80 username@math.hws.edu

Replace username with your CS department username, and enter your CS department password when prompted for a password. This command takes traffic sent to port 9000 on your local machine, sends it over the ssh connection to math.hws.edu, and tells math.hws.edu to then forward it to port 80 (the webserver port) on the repository server. You can change 9000 to something else if you want - it's just a port that is probably not being used by something else. When you set up a repository location, use localhost:9000 (or whatever port you selected) as the hostname.

If you have a laptop that sometimes needs to access the repository from off campus and sometimes from on campus, set up repository locations using both 172.21.7.83 and localhost:9000 and, when you are working, choose the one that matches your current location. You'll also need to create two projects (one linked to each location) and use the appropriate one (be sure to commit when finishing work in one location and update when beginning work in the other), or check out a new working copy (and delete the previous project in Eclipse) each time you start in the other location.


Introduction to Subversive

Subversive provides an SVN client integrated into Eclipse as a plugin.

Subversive provides two new perspectives:

SVN operations like share, check out, update, and commit are found under the Team menu, available by right-clicking in the Package Explorer or a Java editor view in the Java perspective.

Configuring Repository Locations

A repository location is like a bookmark into the repository. Repository locations are used when sharing projects, browsing the repository, and checking out working copies. You will need to set up one for each area of the repository that you access.

Repository locations are configured from the SVN Repository Exploring perspective.

Set up a repository location for your directory within the repository:

If you are working in a group and using someone else's repository directory for the project, you can set up an additional repository location for their directory.

Browsing the Latest Version in the Repository

There are two ways to browse the latest version of files in the repository:


Version Control With Subversive

Package Explorer View

As you do things (share, commit, add files, edit files, etc), observe how the Package Explorer display changes - it provides a lot of information about the current state of things. It is good to get in the habit of checking what it has to tell you.

A working copy can be distinguished from a plain, unversioned project by the URL after the project name (showing what subtree in the repository this working copy corresponds to) and the revision number after each file and directory.

The icons before each file and directory indicate the status:

Basic Workflow

The typical workflow when working with a single branch (known as the trunk) is the following:

  1. create a new project
  2. share project to the repository (creating a working copy)
  3. modify the code
  4. update the working copy
  5. resolve conflicts, if any
  6. commit changes to the repository
  7. modify the code
  8. update the working copy
  9. resolve conflicts, if any
  10. commit changes to the repository
  11. ...
  12. when a significant milestone is achieved (such as a release), create a tag marking that revision

If more than one developer is working on the same project, the other developers can check out their own working copy at any point after the project has been shared. Each developer then has their own modify, update, resolve conflicts, commit cycle.

1. Create a New Project

Try It

One person in each group (person A) should do this.

This program is a simple simulation of a dog door - you can run it to see what it does.

2. Share Project

Sharing puts a project into the repository. All of the project contents except the .classpath and .project files and the .settings directory (and its contents) should go into the repository; these three elements contain environment-specific elements which may not be appropriate if the project is checked out on a different computer.

There are two actions to take: sharing the project, then telling SVN to ignore the files that should remain unversioned so you aren't continually asked about them.

Share

Ignore

The things you chose to ignore should have now disappeared from the Synchronize view.

Finally, save the settings changes by committing:

Try It

Person A should do this.

3. Modify the Code

Try It

Person A should do this.

4-6. Update/Commit

4. Update the Working Copy

Updating transfers changes that have been applied to the repository since the last time you checked out or updated your working copy. It must be done before committing, and may be done any other time you want to incorporate changes from the repository into your working copy.

6. Commit Changes to the Repository

Committing transfers changes that have been made in your working copy to the repository. Commit when you've finished a unit of change such as fixing a bug, implementing a method or class, implementing a feature that affects multiple classes, etc.

All of the icons in the Package Explorer should now be golden icons of synchronicity, and the > symbols should have gone away.

Try It

Person A should do this.

Continue on with another modify/update/commit cycle (still person A):

Getting a New Working Copy

To add additional developers, each needs to check out their own working copy:

It is a good idea to return to the Java perspective (if Eclipse doesn't automatically switch there) and use the Package Explorer to verify that the project just created is a Java project and that it has the correct directory structure - a common mistake is to start with the wrong directory in the check out process. If the project structure is not correct, delete the project (be sure to "Delete project contents on disk") and try again.

Note: By default, Eclipse keeps the Java source files in the src subdirectory and the compiled class files in the bin subdirectory in your project. To keep Eclipse from trying to sneak the bin directory into the repository:

Try It

The other person in the group (person B) should do this.

3. Modify the Code

Try It

Person A should do the following.

In the meantime, person B should do the following.

5. Resolve Conflicts

If there are updates that SVN cannot incorporate automatically, the source file(s) affected are transformed to show the diffs and the Package Explorer shows a red cylinder icon. The transformed file(s) can be edited manually to resolve the conflicts, but it is often easier to use the Compare Editor:

Try It

Person A should commit their version of the dog door (random timing):

Person B should commit their version (slow Fido, bark to open door), which means also integrating the random timing:

Finally, person A should get the latest version:

Now both person A and person B should have working copies with the complete current version of the dog door program.

12. Creating Tags

Tags are essentially labels attached to particular revisions to mark significant milestones, such as a release version.

It is recommended that the working copy be what you want to tag, and that it is up-to-date with some revision in the repository (typically the HEAD revision). (In other words, make sure you have only golden icons of synchronicity in the Package Explorer.)

It is recommended that you check that things worked as expected by browsing the repository - the new tag should be in a subdirectory of tags. (Don't forget to refresh the SVN Repositories view!) If it is not correct, delete the incorrect directory in the repository and try again.

Try It

One use of tags will be to hand in your projects.

Either person can do this.


Miscellaneous

Customizing Perspectives

To make it easier to switch between commonly-used perspectives in Eclipse, you can edit what appears on the Window->Perspective->Open Perspective menu:

If You Have Time

For additional practice with the workflow, repeat the lab, switching roles and trying not to refer back to the detailed instructions earlier in the lab. Be careful to not go through steps too quickly - check over what dialog boxes are telling you before going on to the next step! Note that this is optional and won't be graded.


Valid HTML 4.01!