Using Subversion

From Openmoko

(Difference between revisions)
Jump to: navigation, search
m (WIndows Setup: typo)
(+svnbook link)
Line 84: Line 84:
 
# Isolate Work, Not People
 
# Isolate Work, Not People
 
# Remember Thermodynamics!
 
# Remember Thermodynamics!
 +
 +
== Links ==
 +
[http://svnbook.red-bean.com/ ''Version Control with Subbversion'', eBook by O'Reilly]

Revision as of 14:50, 23 February 2007

Subversion is a free/open-source version control system. That is, Subversion manages files and directories over time. A tree of files is placed into a central repository. The repository is much like an ordinary file server, except that it remembers every change ever made to your files and directories. This allows you to recover older versions of your data, or examine the history of how your data changed. In this regard, many people think of a version control system as a sort of “time machine”.

Contents

Setup

Linux Setup

Overview

If you are using Linux, you are probably don't need more than these very short instructions.

The Process

Use svn, the Subversion command line client:

$ svn co http://svn.openmoko.org/trunk /your/path/to/your/working_copy

Replace /your/path/to/your/working_copy with the actual path to the directory into which you wish to use all the GSM files. Or use a . (period) if you're already in that directory.

wget alternative

If your current computer doesn't have Subversion, you might want to use the repository directly to get the latest files. It's not as efficient and powerful as subversion itself, but it might help. You will need to put your gta01 username and password on the command line, since the files require authentication.

Use the wget tool to do it, as follow:

wget -r -np -nH --cut-dirs=1 --user USER --password PASSWD http://svn.openmoko.org/trunk

Mac OSX Setup

Thanks to its Unix underpinnings, Mac OS X offers several ways to connect to a repository, ranging from conventional Cocoa applications to the use of a command line. Though anyone should be able to follow any of the methods listed below, users are encouraged to choose the approach that best suits their personal workflow and level of technical skills--particularly if they're using Subversion to update a live site.

Graphical User Interface (SVN Approach)

Get either SvnX, scplugin, or iSVN. Download one of them and use.

Command Line Approach

This approach requires permission to use /Applications/Utilities/Terminal.app on your Macintosh (enabled by default) and shell access to your UNIX-based hosting provider. If you do not have access to both of these components, please speak with your system administrator or choose one of the alternate approaches listed above.

Install SVN from the following Metissian Projects Package

Once SVN is installed, take the following steps to checkout the GTA01 sourcode from the SVN repository.

  1. Login to your hosting provider using Terminal.app (probably using ssh).
  2. Move into the directory where you want to download the GTA01 sourcecode, like so: cd /my/gsm/directory/
  3. Run...

svn co http://svn.openmoko.org/trunk . Make certain there is a space between the last trailing slash and the period -- this will not work properly otherwise. Alternatively, you may get the GTA01 sourcecode without moving into the desired directory before (i.e., combine steps 2 and 3 together), by running the command:

svn co http://svn.openmoko.org/trunk /your/path/to/your/working_copy

Future Updates

Once you have initially setup SVN, you simply need to do the following for all future updates.

# cd /your/path/to/your/working_copy
# svn update

Windows Setup

These instructions describe how to get the latest GSM sourcecode from the Subversion repository to your Windows machine using a graphical user interface application called TortoiseSVN.

The Process

Using TortoiseSVN to Download the Source Files
  1. Download and install TortoiseSVN.
  2. Create a local folder with a catchy, but meaningful, name (such as gta01_source). The folder you create here is called your "source" folder, and you should keep it because whenever you update the GSM sourcecode, this is the folder you first update via TortoiseSVN.
  3. Right click on the new folder and you’ll see some new options for TortoiseSVN.
  4. Select 'Checkout' and use the following path for the 'URL of Repository'...
http://svn.openmoko.org/trunk
Updating Your Source Folder

Complete the following steps to update your local code from the SVN repository.

  1. Right click on your GTA01 source folder and select Update.

Developement

Basic Required Definitions

Trunk (or main code line)
The stable line of development suitable for subsequent development efforts.
Branch
A short lived code line that will be merged backed into the trunk.
Tag
A named revision of the trunk (or a branch) for easy access, usually for release.
Merging
The process of integrating code changes, (sometimes an entire branch) back into the contents of the trunk.

The Big Idea

  • Everyone has a working copy of trunk.
  • The trunk must compile and pass regression tests at all times. Developers that break this rule are publicly humiliated :)
  • If a change can be done in a single reviewable commit, then just commit to trunk.
  • If a change needs many commits and/or might destabilize or break code, then do the commits on a temporary branch and merge the branch back into the trunk when done.
  • The releasing/maintenance effort will always branch off the trunk. The trunk will always be the latest and greatest development.

General Advice

  1. Integrate Early and Often
  2. Preserve the Integrity of the Trunk
  3. Isolate Work, Not People
  4. Remember Thermodynamics!

Links

Version Control with Subbversion, eBook by O'Reilly

Personal tools

Subversion is a free/open-source version control system. That is, Subversion manages files and directories over time. A tree of files is placed into a central repository. The repository is much like an ordinary file server, except that it remembers every change ever made to your files and directories. This allows you to recover older versions of your data, or examine the history of how your data changed. In this regard, many people think of a version control system as a sort of “time machine”.

Setup

Linux Setup

Overview

If you are using Linux, you are probably don't need more than these very short instructions.

The Process

Use svn, the Subversion command line client:

$ svn co http://svn.openmoko.org/trunk /your/path/to/your/working_copy

Replace /your/path/to/your/working_copy with the actual path to the directory into which you wish to use all the GSM files. Or use a . (period) if you're already in that directory.

wget alternative

If your current computer doesn't have Subversion, you might want to use the repository directly to get the latest files. It's not as efficient and powerful as subversion itself, but it might help. You will need to put your gta01 username and password on the command line, since the files require authentication.

Use the wget tool to do it, as follow:

wget -r -np -nH --cut-dirs=1 --user USER --password PASSWD http://svn.openmoko.org/trunk

Mac OSX Setup

Thanks to its Unix underpinnings, Mac OS X offers several ways to connect to a repository, ranging from conventional Cocoa applications to the use of a command line. Though anyone should be able to follow any of the methods listed below, users are encouraged to choose the approach that best suits their personal workflow and level of technical skills--particularly if they're using Subversion to update a live site.

Graphical User Interface (SVN Approach)

Get either SvnX, scplugin, or iSVN. Download one of them and use.

Command Line Approach

This approach requires permission to use /Applications/Utilities/Terminal.app on your Macintosh (enabled by default) and shell access to your UNIX-based hosting provider. If you do not have access to both of these components, please speak with your system administrator or choose one of the alternate approaches listed above.

Install SVN from the following Metissian Projects Package

Once SVN is installed, take the following steps to checkout the GTA01 sourcode from the SVN repository.

  1. Login to your hosting provider using Terminal.app (probably using ssh).
  2. Move into the directory where you want to download the GTA01 sourcecode, like so: cd /my/gsm/directory/
  3. Run...

svn co http://svn.openmoko.org/trunk . Make certain there is a space between the last trailing slash and the period -- this will not work properly otherwise. Alternatively, you may get the GTA01 sourcecode without moving into the desired directory before (i.e., combine steps 2 and 3 together), by running the command:

svn co http://svn.openmoko.org/trunk /your/path/to/your/working_copy

Future Updates

Once you have initially setup SVN, you simply need to do the following for all future updates.

# cd /your/path/to/your/working_copy
# svn update

Windows Setup

These instructions describe how to get the latest GSM sourcecode from the Subversion repository to your Windows machine using a graphical user interface application called TortoiseSVN.

The Process

Using TortoiseSVN to Download the Source Files
  1. Download and install TortoiseSVN.
  2. Create a local folder with a catchy, but meaningful, name (such as gta01_source). The folder you create here is called your "source" folder, and you should keep it because whenever you update the GSM sourcecode, this is the folder you first update via TortoiseSVN.
  3. Right click on the new folder and you’ll see some new options for TortoiseSVN.
  4. Select 'Checkout' and use the following path for the 'URL of Repository'...
http://svn.openmoko.org/trunk
Updating Your Source Folder

Complete the following steps to update your local code from the SVN repository.

  1. Right click on your GTA01 source folder and select Update.

Developement

Basic Required Definitions

Trunk (or main code line)
The stable line of development suitable for subsequent development efforts.
Branch
A short lived code line that will be merged backed into the trunk.
Tag
A named revision of the trunk (or a branch) for easy access, usually for release.
Merging
The process of integrating code changes, (sometimes an entire branch) back into the contents of the trunk.

The Big Idea

  • Everyone has a working copy of trunk.
  • The trunk must compile and pass regression tests at all times. Developers that break this rule are publicly humiliated :)
  • If a change can be done in a single reviewable commit, then just commit to trunk.
  • If a change needs many commits and/or might destabilize or break code, then do the commits on a temporary branch and merge the branch back into the trunk when done.
  • The releasing/maintenance effort will always branch off the trunk. The trunk will always be the latest and greatest development.

General Advice

  1. Integrate Early and Often
  2. Preserve the Integrity of the Trunk
  3. Isolate Work, Not People
  4. Remember Thermodynamics!