Lab: Introduction to Version Control With Subversion

Important: Starting with this lab, you are required to work with your partner.

Make sure you follow the steps below very carefully and you ask for help if you have any problems.

Objective

In this lab you will learn how to use the Subversion version control system to share Eclipse projects with your teammate. You will also practice implementing and testing a kernel component, Queue3 implemented on Sequence.

Setup

Starting with this lab, you and your partner will learn to use a version control system (Subversion) to share Eclipse projects for your team work. Here is a summary of the steps involved in using the Subversion team repository you just created for your work in Eclipse. Details follow.

Now that your team has a repository, each team member needs to create a repository location in their workspace to tell Eclipse where the repository is located and how to connect to it. This needs to be done only once for the semester by each team member.
For each new project or lab, one team member needs to create an Eclipse project (as instructed by the project or lab assignment) and share that project by uploading it to the repository. The other team member needs to check out the project from the repository to get a working copy in Eclipse.
Finally, each team member can make changes to his/her working copy of the project and share those changes by committing them to the repository. And each team member can get any changes contributed to the project by his/her partner by updating his/her working copy to the most recent repository version.

Here are the details. Make sure that you and your partner follow these steps together carefully and agree on who is responsible for each step that needs to be done by only one team member.

I. Creating a Repository Location in Eclipse

Now you need to set up Eclipse so that it knows where the repository is. All team members must complete this section on their own computer/account. Start Eclipse and follow these steps:

Select Window > Perspective > Open Perspective > Other... from the menu bar.
Select SVN Repository Exploring and click Open. If this entry is not available on your computer that means you have not installed the Subclipse plugin. You need to follow the instructions on Downloading and Installing Plugins (steps 13-15) and continue after that.
Once the new perspective is displayed, in the SVN Repositories tab on the left, right-click the mouse and select New > Repository Location... in the menu.
In the Add SVN Repository window, enter
```
svn+ssh://coelinux.coeit.osu.edu/share/CSE/project/c2231axnn/repos
```
as the Location Url (making sure to replace c2231axnn with your team group), and click Finish.
In the Enter SSH Credentials window, enter your CSE user name in the Username box, your CSE account password in the Password box, and check the Save information check box. Click OK.
In the Subversion Authentication window, click Yes.
In the Enter Username and Password window, enter again your CSE user name and password, and check the Save Password check box. Click OK.

Your team's repository should now be listed in the SVN Repositories view. If anything went wrong, call an instructor for help. Otherwise, you are ready to start using Subversion.

Switch Eclipse to the Java Perspective by clicking on the Java perspective button in the perspective toolbar at the top right of your Eclipse window.

II. Putting a Project Under Version Control

It is time to create a project for this lab and to add it to your team repository. Only one student per group needs to complete this section. Once one team member is done with this section (and its subsections), the other team member(s) should complete the following section (Getting a Project From the Repository).

Importing a Project for the Lab

For this and most future labs and projects, instead of creating a new project, you will import a project already set-up for you to get started. First you need to download the project, QueueOnSequence.zip, to your computer. Click on this download link and save the file somewhere on your hard drive where you can easily find it. Make sure that you do not expand this archive. If your browser automatically expands downloaded zip archives, that's OK too. Just pay attention to the special instructions in the following few steps. You may want to make a note of where you saved it.

Import your new project into Eclipse by following these steps:

From the File menu select Import....
In the new window, expand General and select Existing Projects into Workspace. Click Next.
Click on the radio button next to Select archive file and then click the Browse... button. (If the archive was expanded when you downloaded the file to your own computer, click on Select root directory... instead.)
In the file selection window, find the QueueOnSequence.zip file and select it. (If your browser expanded the archive, find the QueueOnSequence directory instead.) Click OK.
Click Finish.

Now that you have a project, it is time to add it to the repository to put it under version control and share it with your team.

In the Java perspective and in the Package Explorer view, right-click on the QueueOnSequence project and select Team > Share Project... from the context menu.
In the Share Project window, select SVN in the list and click Next.
In the next window, make sure Use existing repository location is selected and select your new repository location. Click Next.
In the next window, make sure Use project name as folder name is selected. The URL should already be the correct one. Click Next (not Finish yet).
In the next window, edit the commit comment to read
```
Created project.
```
and click Finish.
Eclipse offers to open a new perspective, the Team Synchronizing perspective. In the Confirm Open Perspective window, check the Remember my decision check box, and click Yes.

At this point, Eclipse has just created the project folder in the repository. We still need to commit all the current files in the project to the repository (i.e., synchronize the repository with the current state of the project).

Committing the Initial Project Files to the Repository

The Team Synchronizing perspective is going to be used any time you want to commit your changes to a project to the repository to share them with your team and also whenever you want to update your working copy of a project with any changes your team has committed to the repository.

You should see your project, QueueOnSequence, listed in the Synchronize view. Expand it to see all the files and folders that are going to be added to the repository. Note the little icon (an arrow pointing right with a + on it) that decorates all the files and folders. This decoration indicates that these files/folders need to be committed to the repository because they are new. It points right to show that these files/folders will be transferred from your working copy to the repository (an arrow pointing left would indicate the opposite, i.e., that the files/folders are going to be transferred from the repository to your working copy).

There are various ways to commit your changes in the Team Synchronizing perspective. For now just do the following:

Right-click on the QueueOnSequence project in the Synchronize view and select Commit... from the menu.
In the Commit window, enter
```
Initial import.
```
as the comment for the commit operation. Also note in the bottom half of the window, the list of changes (in this case all additions of new files and folders) that you are about to commit. Click OK.

If everything goes as expected, the commit will take place and the Synchronize view will be empty showing that there are no more changes to be committed. Switch back to the Java perspective. In the Package Explorer view, observe the little "yellow pipe" decorator icon that is superimposed on the icon of all the files and folders that are now under version control.

III. Getting a Project From the Repository

Now that one team member has committed the project to the repository, it is time for the other team member(s) to check out a working copy of the project from the repository. Only a team member who did not complete the previous section needs to do this. Follow these steps:

Switch to the SVN Repository Exploring perspective (by clicking the appropriate button in the toolbar at the top right of the Eclipse window).
In the SVN Repositories view, right-click on the repository location you created earlier and select Refresh from the menu.
Expand the repository location and you should see the QueueOnSequence project listed under the repository location. If you don't, you should call an instructor for help.
Right-click on the QueueOnSequence project and select Checkout... from the context menu.
In the Checkout from SVN window, all the defaults should be correct. Just check that Check out as a project in the workspace is checked and that the Project Name is QueueOnSequence. Click Next.
In the next window, make sure Use default workspace location is checked. Click Finish.

Switch back to the Java perspective. In the Package Explorer view, you should now see the QueueOnSequence project. Observe the little "yellow pipe" decorator icon that is superimposed on the icon of all the files and folders in this project to indicate that they are under version control.

The set-up part of this lab is complete and you can continue with the rest of the lab.

Method

In this part of the lab, you will complete the implementation and testing of Queue3. However, to show you how to use Subversion to share your changes and to get your partner's changes to a project, the steps below will ask each team member to perform some specific actions. Each team member should work on his/her computer/account. But make sure you pay attention to all steps including those performed by your partner. Please follow the instructions carefully and call an instructor if you have problems or questions.

Some of the steps below are labeled TM#1 or TM#2 to indicate which member of the team is supposed to execute that specific sequence of steps. Before you proceed, decide who is team member #1 (TM#1) and who is team member #2 (TM#2). Then make sure you execute the steps you are responsible for in the order provided and wait for your teammate to complete his/her steps before you start on yours. Steps that are not labeled should be executed by all team members.

Take a look at the src and test folders in your new project. Open the Queue3.java file in the src folder and explore it. You will notice that it includes some extra "stuff" that had been removed for the homework—implementations for the Standard methods and support for iteration—but is necessary to have a complete component implementation.
TM#1:
1. Make sure you are in the Java perspective. Complete the body of enqueue in Queue3 in the src folder and save the file. Note in the Package Explorer view that a little asterisk icon has been superimposed on the icon of the Queue3.java file and of all the containing folders to indicate that these resources have been modified in your local copy (and that these changes will be sent to the repository on the next commit action).
2. In the Package Explorer view, right-click on the QueueOnSequence project and select Team > Synchronize with Repository from the menu.
3. The first time you synchronize you may get a confirmation dialog asking whether you want to switch to the Team Synchronizing view. Check the Remember my decision check box and click Yes.
4. In the Synchronize view, expand the QueueOnSequence and the src folders to reveal the file Queue3.java. The right-pointing arrow shows that you made local changes to the file and that those changes are scheduled to be committed to the repository.
5. Before we commit the changes, double-click on Queue3.java. This opens the Compare Editor on the file. This editor compares the original file and the modified one so that you can see what changes you have made and are about to commit. You can close the editor since you already made the changes you want to commit.
6. To commit your change(s) to the repository, right-click on the QueueOnSequence folder in the Synchronize view and select Commit... from the menu.
7. Enter a commit comment, e.g.,
```
Implemented enqueue.
```
  and click OK.
TM#2:
1. Make sure you are in the Java perspective. Complete the body of dequeue in Queue3 in the src folder and save the file. Note in the Package Explorer view that a little asterisk icon has been superimposed on the icon of the Queue3.java file and of all the containing folders to indicate that these resources have been modified in your local copy (and that these changes will be sent to the repository on the next commit action).
2. In the Package Explorer view, right-click on the QueueOnSequence project and select Team > Synchronize with Repository from the menu.
3. The first time you synchronize you may get a confirmation dialog asking whether you want to switch to the Team Synchronizing view. Check the Remember my decision check box and click Yes.
4. In the Synchronize view, expand the QueueOnSequence and the src folders to reveal the file Queue3.java. Note that there is a two-way arrow displayed on Queue3.java. This indicates a (potential) conflict. You made local changes to the file, but your version of the file is not up-to-date with the one in the repository (that was just changed by your teammate).
5. Subversion has the ability to automatically resolve some conflicts when they occur in different sections of the same file. But for now, you should merge the changes manually (if you try to update your local copy and a conflict cannot be resolved automatically, resolving the conflict requires some extra complexity that we want to avoid at this time). Double-click on Queue3.java to open the Compare Editor on the file and copy-paste what you need from the repository file (on the right) into the local copy of the file (on the left). Save the file.
6. When you are done merging the repository file into the local copy, you need to let Eclipse know that the conflicts have been resolved. To do that, right-click on Queue3.java in the Synchronize view and select Mark as Merged from the menu. (Be careful when choosing this option because it will overwrite what is in the repository.)
7. Once the file has been marked as merged, you will see that the two-way arrow has been replaced by a right arrow and you can commit your changes to the repository. Right-click on the QueueOnSequence folder in the Synchronize view and select Commit... from the menu.
8. Enter a commit comment, e.g.,
```
Implemented dequeue.
```
  and click OK.
TM#1:
1. Make sure you are in the Java perspective. If you want to get the new changes committed by your teammate, in the Package Explorer view, right-click on the QueueOnSequence project and select Team > Synchronize with Repository from the menu.
2. In the Synchronize view, expand the QueueOnSequence and the src folders and you'll see a left-pointing arrow displayed on Queue3.java. This indicates that the version in the repository has new changes.
3. Right-click on the QueueOnSequence folder in the Synchronize view and select Update from the menu to update your local copy with the changes in the repository.
4. Switch back to the Java perspective and complete the body of length in Queue3 in the src folder and save the file.
5. Commit your changes as you did before (in the Package Explorer view, right-click on the QueueOnSequence project, select Team > Synchronize with Repository from the menu; in the Synchronize view, right-click on the QueueOnSequence folder and select Commit... from the menu; enter a commit comment and click OK).
TM#2:
1. Make sure you are in the Java perspective. Update your local copy with the most recent changes by following the same steps above (in the Package Explorer view, right-click on the QueueOnSequence project, select Team > Synchronize with Repository from the menu; in the Synchronize view, right-click on the QueueOnSequence folder and select Update from the menu).
Review carefully the JUnit test fixture QueueTest in the test folder. This is provided as both an example of a systematically designed test fixture and as a guide of how to design your own test plans and test cases. After this lab you will be expected to design your own test fixtures as part of lab and project assignments following the same style and with at least the same level of completeness and thoroughness.
Run Queue3Test in the test folder to test your implementation of Queue3. Fix any bugs that you discover and commit your changes to the repository and update your local copy as needed.
The Subclipse (Subversion for Eclipse) plugin provides many other useful features, too many to cover here. One of them is the ability to view the entire history of any of the projects in your repository. Here is how to do it.
1. Switch to the SVN Repository Exploring perspective.
2. In the SVN Repositories view, expand your repository location.
3. Right-click on the QueueOnSequence project and select Show History from the context menu. The history of all changes (the last 25, by default, but you can view more) is displayed by Eclipse. Of course, this history is only as good as the log entries (commit comments) your team has recorded when committing the changes.
Another useful feature is the ability to revert any changes you have made to your local copy of any files or folders. To try this out, follow these steps:
1. Switch to the Java perspective.
2. Edit Queue3.java and save the changes; it does not matter what changes you make since you are going to undo them soon enough.
3. In the Package Explorer view, right-click on the file or folder you want to revert to its state before any changes you applied after the last update. In this case, you can either right-click on the Queue3.java file or the entire QueueOnSequence project (or anything in between). From the menu, select Team > Revert.
4. In the Revert window, you can check all the resources you want to revert and uncheck any resources you do not want to restore to their previous state (after the last update). Click OK and the selected changes will be undone.

Additional Activities

Copy and paste the following piece of code at the end of Queue3 (after the iterator method and before the class closing '}').

    /*
     * Other methods (overridden for performance reasons) ---------------------
     */

    @Override
    public final T front() {
        assert this.length() > 0 : "Violation of: this /= <>";

        // TODO - fill in body

        // This line added just to make the component compilable.
        return null;
    }

Provide a non-layered implementation of the secondary method front defined in Queue.

Why would you want to provide a non-layered implementation of a secondary method that is already implemented in QueueSecondary?