(1) Introduction to Subversion (SVN) and Google Project Hosting Philip Johnson Collaborative Software Development Laboratory Information and Computer Sciences University of Hawaii Honolulu HI 96822

(2) Basic concepts SVN uses a centralized repository. We will not cover repository administration. Clients connect to a repository to download working copies. Working copies: Ordinary directory trees. Contains your files plus administrative files in special subdirectories named '.svn'.

(3) Updates, Commits, Revisions Working copy: A local directory tree Commit: Upload your working copy to the SVN server. Creates a new repository-wide "revision", or snapshot of the state of the repository. Update: Make some or all of your working copy consistent with a given revision. You can update to the - latest revision - any prior revision

(4) Review: Versions/Configurations for RCS/CVS style CM Each file has its own version number. Foo.java (1.1) Foo.java (1.2) Foo.java (1.3) Foo.java (1.4) Foo.java (1.5) Foo.java (1.2.1) Foo.java (1.2.2) Bar.java (1.1) Bar.java (1.2) Bar.java (1.3)

(5) SVN has repository-wide revisions Each time you commit, you 'stamp' not the files you commit with a new version, but the entire repository. File changes color to indicate changed contents, but Subversion doesn’t maintain a file-based “version number”. Foo.java Bar.java 12345

(6) "Copying" in SVN is cheap The database backend in SVN means that you can make "copies" of an SVN directory structure very cheaply. No files are physically copied, just pointers to the files and info on which revision. This means that you create branches, tags, and the "trunk" by creating and merging directories that each contain an entire "copy" of an arbitrary number of files.

(7) Trunk, Branches, Tags SVN project directories are structured by convention with three top-level directories: trunk/ Represents the 'main line' of development with an entire copy of the project. branches/ Contains subdirectories, each holding an entire copy of the project. Each branch constitutes a significant enhancement to the project that can be worked on independently. tags/ Contains subdirectories, each containing one snapshot of the project. Each snapshot represents a "public release" or other archival configuration of the project.

(8) Example /stack/ trunk/ build.xml src/ : tags/ release-1.0/ build.xml src/ : branches/ add-generics/ build.xml src/ : add-intstack/ build.xml src/ :

(9) Trunk vs. Branch Trunk represents "gold" version of system Should always compile, always pass tests. In 413, this means passing the “verify” target! Branches represent "temporary" development streams to implement significant new features. Allow commits to repository without breaking the "gold" version in the trunk. Branches don't need to always compile, pass tests. You must "merge" a branch back into the trunk when completed. Or at intermediate points when branch is "stable". The longer you wait to merge, the more difficult the merge might be.

(10) Our SVN server: Google Google provides a free service for hosting open source projects. Includes: SVN server Mailing lists Issue tracker We will use Google Project Hosting this semester for all class projects. Also good choice for hosting your future open source projects! Alternatives: SourceForge, Java.net

(11) Local SVN Client Choices Upcoming examples of local workspace manipulation use TortoiseSVN client program. Best choice for Windows. Other clients exist for other platforms For Mac I use: SmartSVN

(12) Google Project Hosting Home: Docs:

(13) Google Project Hosting/SVN Use Cases A. Basic Project source download B. Basic daily activities when working with a Project. C. Merge conflicts D. Defining a new Project E. Beyond basic usage

(14) A. Basic Project source download

(15) A. Steps Preconditions: Obtain the URL for the project. Obtain membership in project. Get your SVN password. Setup local folder to hold project contents. SVN 'checkout' the 'trunk' to your folder.

(16) A1. Find Project URL You should be listed as a member or owner.

(17) A2. Find your SVN password Only owners/members have a password. Allows commit (write) access. Don’t worry, I’ve changed this.

(18) A3. Create local folder to hold the sources Example: c:\svn-google\stack-johnson

(19) A4. SVN 'checkout' project to download sources

(20) https vs. http The most common beginner mistake is to check out the project using http, not https. You can check out any Google project using http, whether or not you are a member, but you cannot commit any changes (even if you are a member). If you mistakenly check it out using http, then delete your local directory and start over using https.

(21) B. Basic daily activities when working with a Project

(22) B. Steps 1. Update: "SVN Update" to make your local workspace consistent with latest version from repository. 2. Run "verify" target Make sure your updated local version is running correctly. 3. Edit: Make improvements to the Project files. 4. Run "verify" target Make sure system works correctly before committing! 3. Commit: "SVN Commit" to 'publish' your improvements to the repository.

(23) B1. SVN 'Update' By default, makes your local workspace consistent with the 'head' revision of the 'trunk' in the repository. Right-click project folder, select SVN Update

(24) B2. Run "verify" Ensure you're starting with a working version! If verify target fails: contact your team members! check the project discussion list to see who committed!

(25) B3. Edit files, improve project Locally modified files shown with red ! So are parent directories.

(26) B4. Run "verify" Never commit changes that don't pass verify to trunk!

(27) B5. Publish changes with SVN Commit Select individual files or simply project folder. Right-click, select "SVN Commit" Provide informative commit message.

(28) Informative Commit Messages Informative commit messages indicate: What you did. Why you did it. What Google Issue is being addressed by this commit (if any). Examples of uninformative commit message: “Fixed bugs.” “” Your commit messages will be posted to your project’s discussion list, and so are easily accessable for review.

(29) C. Merge conflicts

(30) C. Steps Sometimes your "SVN commit" will fail Someone else committed changes to the same lines that you modified after the time you last updated your local copy. To fix: Do "SVN Update" to "merge" the other person's commit into your local copy. Make changes to make project consistent. Do "SVN Commit" to commit the new version.

(31) D. Defining a new project

(32) D. Steps 1. Define the new project with Google Project Hosting. Define initial members. Set up mailing lists in google groups. - Add as a member. Get your SVN password. 2. Populate the SVN repository Checkout the 'trunk' directory to a newly created local directory called something like “stack-johnson”. Add project files/directories to that directory. SVN 'add' those files. SVN 'commit' those files.

(33) D1. Creating a repository We will use Google Projects to hold our course projects this semester. Offers an SVN repository Also issue tracking, mailing lists, home page. You must have a GMail account in order to create a Google Project and be signed in.

(34)

(35) D2. Create new project

(36) Project creation confirmation

(37) D3. Create -discuss discussion list Use google groups interface for this.

(38) Set up discussion list Add Also add all other project members. Make group publicly visible; members by invite only.

(39) D4. Add list to Project Send commits and issues to project automatically to the discussion list.

(40) D5. Add owners and members

(41) D6. SVN repository auto-created

(42) Google has a browse mode

(43) And can list changes Bad!

(44) trunk/, branches/, tags/ subdirectories automatically created

(45) D7. Find subversion password Only project owners and members get a password. Passwords allow "commit" (write) access.

(46) D8. Set up your local workspace 1. Create a folder to hold your project: Example: c:\svn-google\stack-johnson

(47) Setting up your local workspace 2. Right-click project folder, select "SVN Checkout". Enter

(48) Setting up your local workspace 3. Enter your gmail account and SVN password to authenticate yourself to the server.

(49) Setting up your local workspace This folder is now a replication of the (empty) "trunk" directory for this project.

(50) D9. Populate the trunk directory with your project Don't include the build or bin directories!

(51) SVN 'Add' your files/directories 1. Don't select the.svn directory! 2. Right-click selected file, select TortoiseSVN | Add

(52) SVN 'Commit' your files 1. Red ! means directory modified, not committed. 2. Right-click project folder, select SVN Commit 3. Enter informative log message.

(53) Files are now in repository And sent to stack-johnson-discuss group.

(54) E. Beyond basic usage SVN has many other useful features: Using branches to isolate development - Most complex part of SVN usage. SVN Blame - Show who committed last version of each line in the file. SVN Switch - Move between trunk, branches, tags. These will be covered later as need arises.

(55) Beginning SVN Basic skills: Checkout existing project, modify, commit. Create new project. Resolve merge conflicts Process simplifications: Commit all changes to "trunk". Never commit if 'verify' doesn't pass. You can go very far and very fast with only "beginner" skills!