Tools

You must configure your Bitbucket account and Mercurial preferences in your local computing account for CS 240. It Is simple.

Bitbucket Account

Do this once per student.

1. Create a Bitbucket account using your .edu email address or add your .edu address if you have an account already. Click through the setup steps choosing default options like “Skip” and “No thanks.”
2. Check your email to confirm your Bitbucket account has unlimited academic access activated.
3. Fill out this form with your name and Bitbucket username.

• Your Bitbucket username is not your email address, even though you may log in by email address.
• To check your Bitbucket username, select the person icon in the upper right corner (old layout) or lower left corner (new layout) and choose “Bitbucket settings”. Look for “Username.”

You must configure your Bitbucket account and Mercurial preferences in your local computing account for CS 240. It Is simple.

Local Account

Do this once per local computing account. (e.g., your CS Linux account, your wx appliance, etc.)

• If you are using a CS Linux machine, run /home/bpw/public/bin/hg-setup.py in a terminal.
  • Run exactly this command.
  • Do not add python in front.
  • Follow the directions the script prints.
• If you are using the wx appliance, this script runs automatically when you first start the appliance.
  • Follow the directions printed in a terminal the first time you start up the appliance.
• CS 240 does not support other platforms

The wx appliance is a virtual machine that provides all the software tools for CS 240. You can run the appliance as an application alongside others on your own computer. The wx appliance is provided for those who wish to work on their own computers without installation headaches, low-level system incompatibliity, or trouble with remote access. Using the appliance is not required. Physical CS Linux machines are always available in the microfocus or S173.

Infrastructure described in this document is still a bit experimental. If your wx appliance stops working, you can replace it easily with a new one, but you might lose all the files you stored on the old one. That means you should backup anything of importance stored on your appliance. Luckily, this is pretty easy if you are using version control to manage your work as we do in this course.

Requirements

Most computers from the last 5 years or so should suffice. You need a computer with:

• a fairly recent 64-bit Intel or AMD x86 processor;
• 4GB or more of RAM (as little as 2GB may work with some tweaking);
• Mac OS X 10.8 or later, Windows Vista SP1 or later, or any recent major distribution of GNU/Linux; and
• 5-6GB of free disk space

Installation

1. Download wx-s17.ova [~1.9 GB] to your computer. This will take a while. Do it on the campus network.
   Alternatively, use scp to get the file if you have a CS account and scp installed (allows access from anywhere, not just campus):
   $ scp your_username@cs.wellesley.edu:~bpw/public_html/wx/s17/appliance/wx-s17.ova .
2. While you are waiting, download and install the latest version of VirtualBox 5.
3. Once wx-s17.ova has finished downloading, start VirtualBox and choose the menu item File > Import Appliance….
4. Click the folder icon and browse to select wx-s17.ova, then click Continue.
5. Click Import to accept the default machine parameters. This will take a few minutes.
6. In the VirtualBox manager application, select the appliance on the left and click the Start button (green arrow) to start up the appliance.
7. Once you are sure the VM started successfully, you can remove the downloaded wx-s17.ova file to save space.
8. Continue to the next section.

User and Initial Setup

The appliance has one user, named wx, that is logged in automatically on startup. The first time the appliance is started, it will automatically run a script that asks you a few questions to get you setup for remote CS access, Bitbucket accesses, and specific courses.

The wx user’s password is wx. When the setup script is done, change the password for security: Open a new terminal and run the command passwd. (We removed fancy GUIs for these sorts of things to save space since you won’t need them much.)

If you have successfully installed and started using your copy of the wx appliance, you can safely delete the wx-s17.ova file that you downloaded.

Startup and Shutdown

The wx appliance can be started and shut down much like a physical computer. It can also be paused. Read the VirtualBox manual to learn how to control it and how it interacts with your mouse and keyboard.

Start up the appliance: open VirtualBox, select wx in the list on the left, and click the Start button. This launches a separate application running the appliance.
Shut down the appliance by clicking the wx menu in the upper right corner of the appliance screen and choosing Shut down.



Do NOT choose Power Off Machine or Reset from the VirtualBox VM Application! These options are equivalent to yanking out the battery or power cord while the computer is running or holding down the power button to hard reset. (Notice the lightning bolt next to that option!) Students who do this end up with corrupted Mercurial repositories. The Send the shutdown signal option is OK. This asks the wx appliance to shut itself down.

Pause and Resume

Pausing and resuming the appliance is convenient if you want to keep some windows open in the appliance but you want to free up resources on your computer while you work on something else.

Pause the appliance by clicking to close the VirtualBox VM window holding the wx screen. Choose Save the machine state and click OK. VirtualBox VM will take a few seconds to save the wx appliance’s current state, then it will close the wx appliance. The listing for the wx appliance in the VirtualBox manager will now show it as Saved (vs. Powered Off). This is like stopping time, and is similar to sleeping/hibernating.

Resume an appliance whose state has been saved the same way you start an appliance.

Software and Licenses

The wx appliance is currently available only to students, faculty, and staff within Wellesley College.

The wx appliance uses a mix of free software and open-source software, plus a couple management tools of our own design that will eventually be released under such licenses.

This section introduces basics of the Mercurial version control system, the hg tool, and the Bitbucket hosting service.

Repository and working copy

A Mercurial repository is a structured record of the evolution of a project through multiple revisions in the form of a detailed revision history of its files.^[1] Mercurial also calls revisions changesets. Every Mercurial repository is paired with a distinct working copy, a directory containing a snapshot of the project, where the user can prepare new revisions.^[2] The repository itself is hidden away (in a hidden directory .hg inside the working copy’s base directory). The user can make direct changes to the working copy, but interacts with the repository (e.g., to record a new revision) only through the interface provided by the Mercurial tool, hg. Mercurial supports several useful repository tasks, including:

• Record a new revision, along with timestamp, creator, and description.
• Reconstruct an arbitrary past revision.
• Compute the difference of two revisions.
• Clone a repository, record independent revisions in separate clones, and share revisions to bring clones up-to-date with each others’ revisions.

Benefits

By allowing interaction with the repository only through its interface, a system like Mercurial abstracts tedious representation and maintenance details away from the error-prone user. The version control software is responsible for principled maintenance of revision history (principles being a great strength of computers) while users are responsible for deciding what versions of a project are appropriate and meaningful to record in the revision history or share revisions with other users.

This model supports a wealth of development tasks such as: quick, reliable, easily recoverable backups; structured collaborative development and sharing of code; structured documentation of project evolution; finding the revision where bug was introduced into the project. Being forced to learn to use principled version control helps you:

• Stop losing hours of work because making backups was just too much work to bother with… until you realize the past 7 hours of untested coding entirely breaks everything.

• Stop sharing code through email. It has a funny habit of multiplying, shifting around, breaking, and disappearing, especially in office hours.

• Stop the scourge of unstructured, unintelligible code-copy litter:

  

• Stop partners from interfering while simultaneously editing on Dropbox or Drive.

• Stop sharing passwords or committing file permissions faux pas in the name of collaboration.

• Start keeping a structured history of development to simplify future debugging tasks.

• Start sharing code easily.

• Start trying out risky new features without losing that precious working version.

• Start learning a fascinating application of data structures and algorithms (particularly DAGs).

• Start getting employed.

A version control system accomplishes none of these improvements on its own, but it helps make the right choice the path of least resistance for you.

Using hg

Mercurial is driven by a command-line tool called hg,^[3] with commands of the form <code>hg <em>command</em></code>.

Driving a command-line tool for the first time can be unsettling, since it is difficult to see the controls. Once you become familiar, however, you may find it easier, quicker, and more expressive than a modern mouse-based GUI. To keep you company on the journey, Mercurial has a friendly help and documentation system built in. Just run the command hg to see the controls.

*Note: in this, and all command line transcripts shown in this document, we use $ to represent the command prompt. Following lines are output from commands entered at the prompt.

$ hg
… output omitted here …


Take note of what it shows (omitted here) and the fact that you can summon this at any time.

hg help shows a longer list of help topics. <code>hg help <em>topic</em></code> shows help about a specific topic. The most common kind of topic is a command. Try running hg help help to see if hg help can help you learn how to use the hg help command.

Bitbucket

Bitbucket is a hosting service for Mercurial and git repositories. We could host repositories the CS server, but the Bitbucket web interface allows flexible permissions. Bitbucket accounts are free; a .edu email address allows unlimited repositories and unlimited collaborators.

Why not git and GitHub?

If you have used or heard of a version control system before, it is probably git (likely with GitHub hosting), the most widely known such tool as of 2017. There are many version control systems available. We use Mercurial for CS240 since it is widely used and has a relatively simple, predictable, and principled interface that is often considered the easiest among its peers for new users to learn quickly. Concepts in git and hg are similar; commands differ.

---

1. Mercurial stores history as differences between versions, rather than snapshots of versions. Each can be reconstructed from the other. ↩

2. Mercurial terminology usually refers to this “next changeset in the making” as the working directory, but we use the alternate term working copy to avoid confusion with the notion of working directory in the shell, as in pwd. ↩

3. The clever Mercurial designers are apparently amateur chemists! ↩

Full Solo Workflow

This section introduces Mercurial and explores skills for simple solo use of Mercurial.

To work with a team, each team member clones the same Bitbucket repository and pushes and pulls revisions through it. Be sure to record your partnership with the form included in the assignment description. Study the diagram below:



We need a few more commands to make this work:

• hg pull acquires new revisions from a remote repository;
  • brings new revisions into the repository, but does not touch the working copy.
• hg incoming shows them but does not acquire them;
• hg update or hg merge integrate them with local revisions.
  • hg update updates the working copy to the most recently added revision.
  • The Update Rule: commit before updating.
  • hg merge merges revisions from another branch of history into the working copy.
  • The Merge Rule: commit before merging and commit immediately after merging (and resolving any conflicts).
• As discussed earlier, hg push shares local revisions with a remote repository.

In this section, work with a partner who also has access to your Bitbucket repository. We will call the Bitbucket repository owner Wendy and her partner Wanda. (It Is OK if Wendy and Wanda are the same person.) Wanda should make a new clone of the Bitbucket repository pointers-wendyw separate from Wendy’s local clone. It is OK if they are on the same computer and even if they are both in Wendy’s local account. They just need to be separate directories.

Resolving Conflicts (in code)

Two divergent changes to the same lines in a file constitute a conflict that cannot be merged automatically. Mercurial is good, but it cannot read your team’s collective mind to decide what to do with a conflict, so it asks you.

For example, imagine both Wendy and Wanda edit the first line in a file, README, to hold different text (i.e., Wendy’s revision and Wanda’s revision should differ in the first line). Both hg commit that change.
Wendy then does a hg push.
Wanda does a hg pull and hg merge, and then observes:



Note several cues in the output: Mercurial tried to merge, but Wendy and Wanda made conflicting changes, so there’s no obvious way to merge and preserve both of their changes. Instead of doing something arbitrary, Mercurial did the following:

• Put the pre-existing working copy of README in README.orig.
  
• Annotate conflicts in README using special notation.
• Mark README as unresolved, such that we cannot commit until explicitly resolving the conflict.
  

Opening up README, we see something like this:

<<<<<<< local, =======, and >>>>>>> other delineate conflicting revisions. The first is from the local working copy. The second is from the other competing revision.
To resolve the conflict, edit the file to remove these markers and save whatever final contents you wish. Then, run hg resolve --mark README to mark README as resolved. Mercurial will refuse to commit if unresolved conflicts remain, to prevent accidental commits of a file full of unmerged conflicts and <<< === >>>.

Finally, live by the merge rule: commit immediately once you have finished merging (and resolved any conflicts), and before making any unrelated changes. The changeset including a merge should include only changes immediately related to merging.

$ hg resolve --mark README
(no more unresolved files)
$ hg commit -m 'Merged README updates'

The Merge Rule: commit before merging and commit immediately after merging (and resolving any conflicts). The changeset including a merge should include only changes immediately related to merging.