SummerOfCodeSubversion [FreeBSD WIKI]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Subversion and Summer Of Code ======

**This document refers to a legacy service which will not be used in future Summer of Code instances**

(This document is currently incomplete, and needs to be finished)

The following is a brief primer for getting started with Subversion for Google Summer of Code.
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%% Summer of Code administrators, who can easily undo anything you may have inadvertently messed up.  As always, if your mentor can't help you, ask [[soc-admins@freebsd.org|Summer of Code administrators]].

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.

===== Setting Up =====

==== Step 1: Getting an Account ====

To obtain a Subversion account, send an email to [[soc-admins@freebsd.org|Summer of Code administrators]] (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 //username//@freebsd.org 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.

<code>
svn mkdir https://socsvn.freebsd.org/socsvn/soc2018/'username'
</code>

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:

<code>
Authentication realm: <https://socsvn.freebsd.org:443> FreeBSD SoC Subversion repository
Password for 'username':
</code>

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:

<code>
Sending        /socsvn/soc2018/'username'
Transmitting file data .
Committed revision 227581.
</code>

==== Step 4: Your first checkout ====

You should be able to now check your tree out:

<code>
svn checkout https://socsvn.freebsd.org/socsvn/soc2018/''username'' ''dirname''
</code>

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:

<code>
svn copy https://socsvn.freebsd.org/socsvn/mirror/FreeBSD/head/ https://socsvn.freebsd.org/socsvn/soc2018/''username''/head/
</code>

Once complete, you can then do a "svn update" in your empty directory, and the full %%FreeBSD%% source tree will be pulled down.

<code>
cd ''/path/to/checkout/''
svn update
</code>

==== 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:

<code>
cd ''/path/to/checkout/''
svn diff
</code>

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:

<code>
cd ''/path/to/checkout/''
svn commit
</code>

And to check just selected files in:

<code>
cd ''/path/to/checkout/''
svn commit path/to/file1 path/to/file2 path/to/file3
</code>

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:

<code>
cd ''/path/to/checkout''
svn add ''path/to/newfile''
</code>

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:

<code>
cd ''/path/to/checkout''
svn delete ''path/to/gonefile''
</code>

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**:

<code>
cd ''/path/to/checkout''
svn log ''path/to/file'' | less
</code>

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:

<code>
cd ''/path/to/checkout''
svn diff -c ''revison'' | less
</code>

Or to just see the changes made to particular files in that commit:

<code>
cd ''/path/to/checkout''
svn diff -c ''revison'' path/to/file| less
</code>

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:

<code>
cd ''/path/to/checkout''
svn diff -r ''revision'' ''path/to/file'' | less
</code>

===== 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.

----

{{tag>HowTo Historical Gsoc}}