Subversion and Summer Of Code
(This document is currently incomplete, and needs to be finished)
The following is a brief primer for getting started with Subversion for Google SummerOfCode. Follow these instructions to familiarize yourself with Subversion, and ask your mentor about any problems you have. If you get really stuck, your mentor can get help from the FreeBSD SummerOfCode administrators, who can easily undo anything you may have inadvertently messed up. As always, if your mentor can't help you, ask email@example.com.
We recognize that some of you may prefer other version control systems, and as a result students may use tools like git-svn to access the socsvn repository.
Additional documentation, including more detail about some key topics and a number of useful recipes, can be found at: http://www.freebsd.org/doc/en_US.ISO8859-1/articles/committers-guide/subversion-primer.html, however this is aimed towards working with the main FreeBSD repository so some of the information may not directly apply to the Summer of Code repository.
Subversion and Summer Of Code
- Setting Up
- Working with history
- Interactions between the main Repository and SoCSVN
Step 1: Getting an Account
To obtain a Subversion account, send an email to firstname.lastname@example.org (and CC your mentor, please) providing the following information:
- Desired username: Please provide first, second, and third choices. Names should be Unix-style names (no more than 8 characters, all lowercase ASCII letters and digits).
Email address: We'll create a username@FreeBSD.org alias that will forward to this address. All of your Subversion email will go to this address.
Branch setup: We can create an initial branch for you of the full FreeBSD tree or any part of it, or we can create an empty branch and you can set it up yourself. Talk to your mentor to determine how much of the system you need and we'll set up the necessary machinery for you. (Step 5 below explains how you could do this yourself if you want.)
You should get a response within a few days with your Subversion username and password. You should:
Send email to email@example.com and verify that it is correctly forwarded to your regular email account. In particular, you may need to adjust spam filters.
- Read the tutorial below and actually do most all of it to make sure you're comfortable with Subversion.
Step 2: Installing Subversion client binaries
Any of the following should suffice to install the Subversion svn client on a FreeBSD system:
- pkg_add -r subversion
- portupgrade -N devel/subversion
cd /usr/ports/devel/subversion && make && make install
Client software for non-FreeBSD systems is available, although we recommend that you do all your work from your FreeBSD system.
Step 3: Creating your working area
Once your Subversion account has been set up, you should be able to create your working area.
Firstly, make yourself a directory in which to do all your work.
svn mkdir https://socsvn.freebsd.org/socsvn/soc2013/'username'
If this is the first time you have accessed this server, you might be prompted to accept the server SSL certificate. If this happens, say no, and install the ca_root_nss package.
You will then be asked for your password:
Authentication realm: <https://socsvn.freebsd.org:443> FreeBSD SoC Subversion repository Password for 'username':
Enter your password at the prompt. If you are prompted with a different username to the one that you have had created @FreeBSD.org, just press enter at the "password" prompt, and you'll be prompted to enter your username and then password.
If all goes well, you should see the new directory being created:
Sending /socsvn/soc2013/'username' Transmitting file data . Committed revision 227581.
Step 4: Your first checkout
You should be able to now check your tree out:
svn checkout https://socsvn.freebsd.org/socsvn/soc2013/''username'' ''dirname''
Replace dirname with a local directory name where your work will be located (perhaps "gsoc"). You will only need to enter your password when checking code in.
As nothing has yet been committed to your tree, you'll end up with just an empty directory. However this will be enough to test basic Subversion operations.
Step 5: Branch a copy of the FreeBSD tree
Generally, Summer of Code students working with the FreeBSD src tree will be working on the head branch. To make a copy of the head branch to work with, you should copy it from the FreeBSD mirror:
svn copy https://socsvn.freebsd.org/socsvn/mirror/FreeBSD/head/ https://socsvn.freebsd.org/socsvn/soc2013/''username''/head/
Once complete, you can then do a "svn update" in your empty directory, and the full FreeBSD source tree will be pulled down.
cd ''/path/to/checkout/'' svn update
Step 6: Modifying files
Go ahead and edit your tree as you need to. Once you are ready to commit work, you can look at the changes you are about to commit:
cd ''/path/to/checkout/'' svn diff
This will show you a unified diff of your changes. These can take a little getting used to reading, but essentially lines starting with "+" have been added, and lines starting with "-" have been removed.
You can then either commit all of your changes, or just check selected files in. To commit all changes:
cd ''/path/to/checkout/'' svn commit
And to check just selected files in:
cd ''/path/to/checkout/'' svn commit path/to/file1 path/to/file2 path/to/file3
Once you do this, you will be dropped into an editor in which you can explain your changes. Please try to give good, detailed commit messages - a good commit message documents what is being changed and why, perhaps for example also including an example of how to trigger a bug, if the commit is fixing one. Once written, save and exit the editor, and your change will be committed.
There is no way of checking in just a subset of changes within one file. We would generally recommend checking in your whole tree each time - it helps us keep track of your progress, and also acts as a backup should anything bad happen to your checked out FreeBSD tree.
Step 7: Adding a new file
If you have created a new file, you need to add it before it will be committed to the repository:
cd ''/path/to/checkout'' svn add ''path/to/newfile''
It will then be committed when you next svn commit.
Step 8: Delete a file
If you need to remove a file, you need to delete it before it will be committed to the repository:
cd ''/path/to/checkout'' svn delete ''path/to/gonefile''
It will then be removed when you next svn commit.
Working with history
One of the advantages of using a revision control system is that no work is ever lost. As long as you checked your work in, that copy can always be accessed. In all of these examples, revision refers to the revision number, for example 249960.
To view the log of changes affecting any particular file, you can use svn log:
cd ''/path/to/checkout'' svn log ''path/to/file'' | less
This will show you the full history of the file since the day it was created. As your repository is a copy of the FreeBSD repository, this history could well go back 20 years - although the newest changes will be at the top.
To see all changes made by a particular commit:
cd ''/path/to/checkout'' svn diff -c ''revison'' | less
Or to just see the changes made to particular files in that commit:
cd ''/path/to/checkout'' svn diff -c ''revison'' path/to/file| less
If you want to see all changes made between your copy, and how the file looked at a particular revison in history, you can do this too:
cd ''/path/to/checkout'' svn diff -r ''revision'' ''path/to/file'' | less
Interactions between the main Repository and SoCSVN
The main FreeBSD repository and the SoCSVN repository are completely separate. However, changes to the main Subversion repository are replicated once an hour into SoCSVN. This tree is then available for copying and merging into derivative projects, as /mirror/FreeBSD. Any project that directly modifies that FreeBSD source code should have this tree as its branch parent (or grandparent, depending on the needs), and periodic merges should be done so that your tree stays up to date and avoids conflicts with mainline development.
The bridge between the primary Subversion repository and SoCSVN is one-way; changes to the main repository will be reflected in SoCSVN, but changes in SoCSVN will not be reflected in the primary repository.