Software Development Tools: Part I

Software Development Tools

Part I: Version Control

Conrad Huang

May 22, 2009

Portions Copyright © 2005-06 Python Software Foundation.

Introduction: Version Control

  • Four things distinguish professional programmers from amateurs:
    • Using a version control system
    • Automating repetitive tasks
    • Systematic testing
    • Using debugging aids rather than print statements
  • This lecture introduces the first of these
    • Even if it's the only thing you take away from this course, you'll be more productive than you are now

Problem #1: Collaboration

  • What if two or more people want to edit the same file at the same time?
  • Option 1: make them take turns
    • But then only one person can be working at any time
    • And how do you enforce the rule?
  • Option 2: patch up differences afterwards
    • Requires a lot of re-working
    • Stuff always gets lost

Solution: Version Control

  • The right solution is to use a version control system
  • Keep the master copy of the file in a central repository
  • [Managing Multi-Author Collaboration]

    Figure 5.1: Managing Multi-Author Collaboration

  • Each author edits a working copy
  • When they're ready to share their changes, they commit them to the repository
  • Other people can then do an update to get those changes
  • This is also a good way for one person to manage files on multiple machines
    • Keep one working copy on your personal laptop, the lab machine, and the departmental server
    • No more mailing yourself files, or carrying around a USB drive (and forgetting to copy things onto it)

Problem #2: Undoing Changes

  • Often want to undo changes to a file
    • Start work, realize it's the wrong approach, want to get back to starting point
    • Like "undo" in an editor…
    • …but keep the whole history of every file, forever
  • Also want to be able to see who changed what, when
    • The best way to find out how something works is often to ask the person who wrote it

Solution: Version Control (Again)

  • Have the version control system keep old revisions of files
    • And have it record who made the change, and when
  • [Version Control as a Time Machine]

    Figure 5.2: Version Control as a Time Machine

  • Authors can then roll back to a particular revision or time

Which Version Control System?

  • CVS and Subversion are:
    • Open source
    • Reliable
    • Well documented
  • CVS has been around since the 1980s
    • Very popular, but showing its age
    • Flaw #1: it keeps track of each file separately
      • So there's no reliable way to ask, "Which files were changed together?"
    • Flaw #2: you can create new directories, but can't delete old ones
  • Subversion (svn) developed from 2000 onward as a workalike replacement
    • Feels the same, but eliminates CVS's major weaknesses
    • Many projects have already switched

Basic Use

  • Ron and Hermione each has a working copy of the solarsystem project repository
    • See below how they got it
  • Ron wants to add some information about Jupiter's moons
    • Runs svn update to synchronize his working copy with the repository
    • Goes into the jupiter directory and creates moons.txt
    • Name            Orbital Radius  Orbital Period  Mass            Radius
      Io              421.6           1.769138        893.2           1821.6
      Europa          670.9           3.551181        480.0           1560.8
      Ganymede        1070.4          7.154553        1481.9          2631.2
      Callisto        1882.7          16.689018       1075.9          2410.3
      
    • Runs svn add moons.txt to bring it to Subversion's notice
    • [The Basic Edit/Update Cycle]

      Figure 5.3: The Basic Edit/Update Cycle

    • Runs svn commit to save his changes in the repository
      • Repository is now at revision 121
  • That afternoon, Hermione runs svn update on her working copy

How To Do It

    [RapidSVN]

    Figure 5.4: RapidSVN

  • One way to use Subversion is to type commands in a shell
    • A lowest common denominator that will work almost everywhere
  • RapidSVN is a GUI that runs on Windows, Linux, and Mac
    • Well, maybe "walks" is a better description—Version 0.9 isn't particularly fast
  • [TortoiseSVN]

    Figure 5.5: TortoiseSVN

  • TortoiseSVN is a Windows shell extension
    • Integrates with the file browser, rather than running separately

Resolving Conflicts

Example of Resolving

  • Ron and Hermione are both synchronized with version 151 of the repository
  • Ron edits moons.txt and commits his changes to create version 152
  • Name            Orbital Radius  Orbital Period  Mass            Radius
    Io              421.6           1.769138        893.2           1821.6
    Europa          670.9           3.551181        480.0           1560.8
    Ganymede        1070.4          7.154553        1481.9          2631.2
    Callisto        1882.7          16.689018       1075.9          2410.3
    Amalthea        181.4           0.498179        0.075           131 x 73 x 67
    Himalia         11460           250.5662        0.095           85
    Elara           11740           259.6528        0.008           40
    
    [Merging Conflicts]

    Figure 5.6: Merging Conflicts

  • Simultaneously, Hermione edits her copy of moons.txt
  • Name            Orbital Radius  Orbital Period  Mass            Radius
                    (10**3 km)      (days)          (10**20 kg)     (km)
    Io              421.6           1.769138        893.2           1821.6
    Europa          670.9           3.551181        480.0           1560.8
    Ganymede        1070.4          7.154553        1481.9          2631.2
    Callisto        1882.7          16.689018       1075.9          2410.3
    Amalthea        181.4           0.498179        0.075           131
    Himalia         11460           250.5662        0.095           85
    Elara           11740           259.6528        0.008           40
    Pasiphae        23620           743.6           0.003           18
    Sinope          23940           758.9           0.0008          14
    Lysithea        11720           259.22          0.0008          12
    
  • When she tries to commit, Subversion tells her there's a conflict
    • A race condition : two or more would-be writers racing to get their changes in first

Example of Resolving (continued)

  • Subversion puts Hermione's changes and Ron's in moons.txt
    • Adds conflict markers to show where they overlapped
    • Name            Orbital Radius  Orbital Period  Mass            Radius
                      (10**3 km)      (days)          (10**20 kg)     (km)
      Io              421.6           1.769138        893.2           1821.6
      Europa          670.9           3.551181        480.0           1560.8
      Ganymede        1070.4          7.154553        1481.9          2631.2
      Callisto        1882.7          16.689018       1075.9          2410.3
      <<<<<<< .mine
      Amalthea        181.4           0.498179        0.075           131
      Himalia         11460           250.5662        0.095           85
      Elara           11740           259.6528        0.008           40
      Pasiphae        23620           743.6           0.003           18
      Sinope          23940           758.9           0.0008          14
      Lysithea        11720           259.22          0.0008          12
      =======
      Amalthea        181.4           0.498179        0.075           131 x 73 x 67
      Himalia         11460           250.5662        0.095           85
      Elara           11740           259.6528        0.008           40
      >>>>>>> .r152
      
    • <<<<<<< shows the start of the section from the first file
    • ======= divides sections
    • >>>>>>> shows the end of the section from the second file
  • Subversion also creates:
    • moons.txt.mine: contains Hermione's changes
    • moons.txt.151: the file before either set of changes
    • moons.txt.152: the most recent version of the file in the repository

Example of Resolving (continued)

  • At this point, Hermione can:
    • Run svn revert moons.txt to throw away her changes
    • Copy one of the three temporary files on top of moons.txt
    • Edit moons.txt to remove the conflict markers
  • Once she's done, she runs:
    • svn resolved moons.txt to let Subversion know she's done
    • svn commit to commit her changes (creating version 153 of the repository)

Starvation

  • But what happens if Ginny commits another set of changes while Hermione is resolving?
    • And then Harry commits yet another set?
  • Starvation : Hermione never gets a turn because someone else always gets there first
  • This is a management problem, not a technical one
    • Break the file(s) up into smaller pieces
    • Give people clearer responsibilities
    • The version control system is trying to tell you that people on your team are working at cross purposes

Binary Files

  • Subversion can only merge conflicts in text files
    • Source code, HTML—basically, anything you can edit with Notepad, Vi, or Emacs
  • But images, video clips, Microsoft Word, and other formats aren't plain text
    • When there's a conflict, Subversion saves your copy and the master copy side by side in your working directory
    • Up to you to resolve the differences
  • It's not Subversion's fault
    • Most creators of non-text formats don't provide a way to find or merge differences between files

Reverting

  • After doing some more work, Ron decides he's on the wrong path
  • svn diff shows him which files he has changed, and what those changes are
  • He hasn't committed anything yet, so he uses svn revert to discard his work
    • I.e., throw away any differences between his working copy and the master as it was when he started
    • Synchronizes with where he was, not with any changes other people have made since then
  • If you find yourself reverting repeatedly, you should probably go and do something else for a while…

Rolling Back

  • Now Ron decides that he doesn't like the changes Harry just made to moons.txt
    • Wants to do the equivalent of "undo"
  • [Rolling Back]

    Figure 5.7: Rolling Back

  • svn log shows recent history
    • Current revision is 157
    • He wants to revert to revision 156
  • svn merge -r 157:156 moons.txt will do the trick
    • The argument to the -r flag specifies the revisions involved
    • Merging allows him to keep some of Harry's changes if he wants to
    • Revision 157 is still in the repository

Creating and Checking Out

  • To create a repository:
    • Decide where to put it (e.g., /svn/rotor)
    • Go into the containing directory: cd /svn
    • svnadmin create rotor
  • Can then check out a working copy
    • Directly through the file system: svn checkout file:///svn/rotor
    • Through a web server: svn checkout http://www.hogwarts.edu/svn/rotor
      • Note: requires your system administrator to configure the web server properly
  • Only use svn checkout once, to initialize your working copy
    • After that, use svn update in that directory
  • If you only want part of the repository, use svn co http://www.hogwarts.edu/svn/rotor/engine/dynamics

Subversion Command Reference

Name Purpose Example
svn add Add files and/or directories to version control. svn add newfile.c newdir
svn checkout Get a fresh working copy of a repository. svn checkout https://your.host.name/rotor/repo rotorproject
svn commit Send changes from working copy to repository (inverse of update). svn commit -m "Comment on the changes"
svn delete Delete files and/or directories from version control. svn delete oldfile.c
svn help Get help (in general, or for a particular command). svn help update
svn log Show history of recent changes. svn log --verbose *.c
svn merge Merge two different versions of a file into one. svn merge -r 18:16 spin.c
svn mkdir Create a new directory and put it under version control. svn mkdir newmodule
svn rename Rename a file or directory, keeping track of history. svn rename temp.txt release_notes.txt
svn revert Undo changes to working copy (i.e., resynchronize with repository). svn revert spin.h
svn status Show the status of files and directories in the working copy. svn status
svn update Bring changes from repository into working copy (inverse of commit). svn update
Table 5.1: Common Subversion Commands

Reading Subversion Output

  • svn status compares your working copy with the repository
    • Prints one line for each file that's worth talking about
    •  $ svn statusM jupiter/moons.txtC readme.txt
    • jupiter/moons.txt has been modified
    • readme.txt has conflicts
  • svn update prints one line for each file or directory it does something to
      $ svn updateA saturn/moons.txtU mars/mars.txt
    • saturn/moons.txt has been added
    • mars/mars.txt has been updated (i.e., someone else modified it)

Summary: Version Control

  • Version control is one of the things that distinguishes professionals from amateurs
    • And successful projects from failures
  • Everything that a human being had to create should be under version control
  • You'll see the benefits almost immediately


Exercises

Exercise 5.1:

  • Follow the instructions given to you by your instructor to check out a copy of the Subversion repository you'll be using in this course. Unless otherwise noted, the exercises below assume that you have done this, and that your working copy is in a directory called course. You will submit all of your exercises in this course by checking files into your repository.

Exercise 5.2:

  • Create a file course/ex01/bio.txt (where course is the root of your working copy of your Subversion repository), and write a short biography of yourself (100 words or so) of the kind used in academic journals, conference proceedings, etc. Commit this file to your repository. Remember to provide a meaningful comment when committing the file!

Exercise 5.3:

  • What's the difference between mv and svn mv? Put the answer in a file called course/ex01/mv.txt and commit your changes.
  • Once you have committed your changes, type svn log in your course directory. If you didn't know what you'd just done, would you be able to figure it out from the log messages? If not, why not?

Exercises

Exercise 5.4:

  • In this exercise, you'll simulate the actions of two people editing a single file. To do that, you'll need to check out a second copy of your repository. One way to do this is to use a separate computer (e.g., your laptop, your home computer, or a machine in the lab). Another is to make a temporary directory, and check out a second copy of your repository there. Please make sure that the second copy isn't inside the first, or vice versa—Subversion will become very confused.
  • Let's call the two working copies Blue and Green. Do the following:
    1. Create Blue/ex01/planets.txt, and add the following lines:
    2. Venus
      Earth
      Mars
      Jupiter
      Saturn
      
      Commit the file.
    3. Update the Green repository. (You should get a copy of planets.txt.)
    4. Change Blue/ex01/planets.txt so that it reads:
      1. Venus
      2. Earth
      3. Mars
      4. Jupiter
      5. Saturn
      
      Commit the changes.
    5. Edit Green/ex01/planets.txt so that its contents are as shown below. Do not do svn update before editing this file, as that will spoil the exercise.
    6. Venus 0
      Earth 1
      Mars 2
      Jupiter 16 (and counting)
      Saturn 14 (and counting)
      
    7. Now, in Green, do svn update. Subversion should tell you that there are conflicts in planets.txt. Resolve the conflicts so that the file contains:
    8. 1. Venus 0
      2. Earth 1
      3. Mars 2
      4. Jupiter 16
      6. Saturn 14
      
      Commit the changes.
    9. Update the Blue repository, and check that planets.txt now has the same content as it has in the Green repository.

Exercises

Exercise 5.5:

  • Add another line or two to course/ex01/bio.txt and commit those changes. Then, use svn merge to restore the original contents of your biography (course/ex01/bio.txt), and commit the result. When you are done, bio.txt should look the way it did at the end of the first part of the previous exercise.) Note: the purpose of this exercise is to teach you how to go back in time to get old versions of files—while it would be simpler in this case just to edit bio.txt, you can't (reliably) do that when you've made larger changes, to multiple files, over a longer period of time.

Exercise 5.6:

  • Subversion allows users to set properties on files and directories using svn propset, and to inspect their values using svn propget. Describe three properties you might want to change on a file or directory, and how you might use them in your current project.