Accessing Your Project Group's Repository Via Eclipse and Mercurial

The following explains how to access your project group's repository and describes a simple test you should do to ensure you understand the basics of using mercurial for group work.

The initial set up will only allow you to access the repository from your ANU account (ie within the lab). At the end of these instructions, you will find instructions on how to add keys for other computers, so that you can access your group repository from your laptop or home computer, if you wish.

I have started listing common pitfalls at the end of this document. If you run into trouble, please check that list and see if your problem matches one of the common pitfalls.

Important: at this stage we have not discussed the dynamics of dealing with conflicting access to a version control system. For now you should observe the following very conservative and simple rules whenever using your group repository, to avoid having to deal with conflicting changes:

1. Never have more than one person editing a given file at a time. Use email or speak to each other to ensure you know who is editing a given file. Announce your intentions before editing a file that is checked in to your repository.
2. Always "pull" and then "update" changes before starting to work on your code.
3. Always "commit" and "push" your changes promptly, and alert your colleagues to the change.

These restrictions can be softened once you know more about mercurial and become more ambitious in its use. In the meantime, a conservative approach is a good idea. Remember that the master repository resides on the server. If you really mess up your local copy, then you can always move it (give it a different name) or delete it, and re-clone the master, starting with a clean slate.

Background: You do not need read this paragraph to get things working, but doing so may shed some light on some the instructions. The group repositories have been created using mercurial-server, which uses ssh to mediate access to repositories. This means: a) you will access the repository via ssh (whether you are using the lab machines or your home machine), and b) you will do so via the "user" called hg. The way it works in practice is that your public key is able to gain you access to the hg account, but only to those repositories for which you are registered.

Cloning Your Group Repo

The steps for cloning your group repo are very similar to those for cloning the lecture code. The principal differences are:

• You use the following url: ssh://partch.anu.edu.au/<groupid>, where <groupid> is something like tue09a (check with your tutor if you're unsure).
• You use the username hg.
• You will be able to push your changes, so that your peers can see them (the lecture code is read-only).

Now do the following to clone the repository:

1. Before you begin, ensure that you are able to ssh into partch.anu.edu.au. To do this, open a terminal, and type "ssh partch.anu.edu.au". If prompted about adding partch to your list of known hosts, type "yes". Once you've done that you can close the terminal and continue with these instructions.
2. Within Eclipse, use "File", "New...", "Other...", and select "Clone Existing Mercurial Repository".
   
3. Type in the appropriate URL the lecture code repository (ssh://partch.anu.edu.au/<groupid>, where <groupid> is something like tue09a (check with your tutor if you're unsure>.)), and then press "Next". If, when you attempt to do this step, you get a dialog relating to ssh not knowning the host partch.anu.edu.au, you apparently have not got the previous step working correctly. Try again and/or seek help from your tutor.
   
4. You should now have a new project, which has the same name as your group.
5. Your cloned copy does not yet have its build path set up (because the build path varies from computer to computer, so I did not check it in to the repository). You should now right click over the project name and choose "Properties". You should see something like the following. Choose "Java Build Path".
   
6. You should see something like this. If you do not see a "JRE System Library [JavaSE-1.7]" (or "JavaSE 7", or similar, indicating that you have a 1.7 JRE), then you will need to remove the incorrect one (use the "Remove" button), and then add the JRE (use the "Add Library", and then "JRE System Library"). Once you do see the following, then you will need to add the Java FX jar (you won't need JavaFX for this exercise, but you will need it for your assignment).
   
7. Click on "Add External JARs...".
   
8. Use the file selector to navigate to /usr/local/javafx/rt/lib/jfxrt.jar or wherever jfxrt.jar is on your system. (In the labs, you'll need to click on "File System" to get to the root of the file system, so you can find /usr. (Under some circumstances on the Mac, you can't navigate through to the correct location. If you encouter this, you can create a link from the jar to your desktop then navigate to the link).
   
9. The dialog should now look like this. Press "OK".
   
10. You should find that your project is marked with a little black mark with a white star, indicating outstanding changes. This reflects the fact that you have changed eclipse's .project file for your group project. You do not want to commit those changes because they are specific to you, and may not work for your colleagues. So you will leave that change to your project settings uncommitted for the remainder of the semester.
11. You will also have changed your .classpath file (eclipse will have done it for you). However, this change won't be committed because your repository has a .hgignore file which stipulates files that you do not want to be under version control, and your .hgignore file lists .classpath as a file to be ignored.

Testing Your Group Repo

You should complete the following steps to familiarize yourselves with basic operation of the repository, and show your tutor during your lab in week 5. You will need to co-ordinate with your group members to make this work.

1. One (only one!) group member should create a simple Java program called HgTest, that prints out that group member's name.
   1. Create a new class HgTest within your new project (it should appear under your src folder).
   2. Ensure the class can print out your name when run.
   3. Add the new class to your local copy of the repository (right mouse click on the class name, select "Team...", "Add...").
   4. Commit your change (right mouse click on the class name, select "Team...", "Commit...").
   5. Push your change (right mouse click on the project name, select "Team...", "Push...").
2. The other group member(s) should pull the changes, edit the file to also print their names, and the commit the changes, each member doing the following, one member at a time:
   1. Either clone the repository (above) if you've not already done so, or else update your copy of the repository (right mouse click on the project name, select "Team...", "Pull...", then "Team...", "Update...").
   2. You should now have a copy of HgTest. Open that file and edit so that it prints out your name, save it and test it.
   3. Commit your change (right mouse click on the class name, select "Team...", "Commit...").
   4. Push your change (right mouse click on the project name, select "Team...", "Push...").
3. Demonstrate your resulting program to your tutor. Try looking at the revision history for HgTest (right click the file, select "Team...", "Show History").
4. Once you've finished, one group member can delete the test file, HgTest:
   1. Before deleting, ensure you are up to date (right mouse click on the project name, select "Team...", "Pull...", then "Team...", "Update...").
   2. Right-click on the file and select "Delete".
   3. Right-click on the project name and select "Team...", "Commit...". Check the dialog box and note that it will remove the file that you had deleted.
   4. Right-click on the project name and select "Team...", "Push..."
   5. Other group members should now ensure they are up to date (right mouse click on the project name, select "Team...", "Pull...", then "Team...", "Update...").

Pitfalls

I will try to document as many common pitfalls as I can. If you find yourself in trouble, please consult this list.

1. Deleting src folder. When you delete the last file in a folder, mercurial will by default delete the empty folder too. So if you have only one class in your src folder, and you delete that class, then your src folder will vanish, leaving Eclipse unhappy (with a red exclamation mark next to your project). This looks bad and is confusing, but it is easy to fix. Just right-click on your project, and select "New..." "Folder...", and then name the new folder src. Once you press OK, you should find the familiar src folder return and the red exclamation mark go away.
2. All commits are tagged with user "hg". When you commit a change ("Team..." "Commit..."), a dialogue will come up. That dialogue will insist that you enter a commit message. Right below the commit message pane, there is a field for writing your name ("User to record as committer:"). You should put your name or nickname there (e.g. "Steve", "Bob", etc). The changeset generated by that commit will then be tagged with the name you entered. When you commit subsequently, that dialogue will default to whatever you typed last (so you should not need to think about this again). Note the name you enter in that dialogue can be (will be) entirely different to the one that is used to authenticate with the server when you push. You will notice next time you push that even though you changed the committer to your name, the "Username" used when pushing to partch will remain "hg".

Remote Access: Adding Extra Keys

You will notice within your project a directory called keys which has a sub-directory for each group member, each of which contains one or more keys. That initial set of keys was established by our tech support people and will allow you to access the repo from the lab.

You may add additional keys to the subdirectory corresponding to your uid. Every 15 mins, starting on the hour, a script will run on a server which will check for the addition of new keys, and install them, granting access to your repo from all computers that hold the corresponding private key. So once you have added, committed, and pushed additional keys, you should find that within 15 mins you can use the instructions above to access your repo from the computers whose keys you added.

I suggest you achieve the above by copying your public key (a file with a .pub suffix) from your home computer into your lab computer using email, scp or pscp (a step you will have already performed at least once in setting up ssh access to the lab computers, for example, step 4 of the instructions for windows). Then go to the lab and add your new public key/s into your subdirectory of the group's keys directory, add, commit and then push.

If you find that after adding the appropriate keys you still cannot access the repo from your laptop or home computer, first ensure that you can ssh from your laptop or home computer to partch.anu.edu.au without being prompted for a password. If you can do this, but you can't access the repo (remember that keys are only updated every 15 min), see your tutor or me. If you cannot ssh from your laptop or home computer without a password, you need to get that working before you attempt to access the repo.