Using Subversion

From Openmoko

(Difference between revisions)
Jump to: navigation, search
m (The Process)
(catchg)
 
(11 intermediate revisions by 7 users not shown)
Line 4: Line 4:
 
=== Linux Setup ===
 
=== Linux Setup ===
 
==== Overview ====
 
==== Overview ====
If you are using Linux, you are probably don't need more than these very short instructions.
+
If you are using Linux, then you probably don't need more than these very short instructions.
  
 
==== The Process ====
 
==== The Process ====
Line 14: Line 14:
  
 
==== wget alternative ====
 
==== 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.
+
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:
 
Use the wget tool to do it, as follow:
  
  wget -r -np -nH --cut-dirs=1 {{svn_trunk}}
+
  wget -r -np -nH --cut-dirs=1 --user USER --password PASSWD {{svn_trunk}}
  
 
=== Mac OSX Setup ===
 
=== Mac OSX Setup ===
Line 48: Line 48:
 
  # svn update
 
  # svn update
  
=== WIndows Setup ===
+
=== 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 [http://tortoisesvn.tigris.org/download.html TortoiseSVN].
+
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 [http://tortoisesvn.net/downloads TortoiseSVN].
  
 
==== The Process ====
 
==== The Process ====
 
===== Using TortoiseSVN to Download the Source Files =====
 
===== Using TortoiseSVN to Download the Source Files =====
 
# Download and install TortoiseSVN.
 
# Download and install TortoiseSVN.
# 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.
+
# 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. If you're using version 1.4.4 (the latest, as of 7/10/07) of TortoiseSVN, please skip down to the alternate update method below.
# Right click on the new folder and you’ll see some new options for TortoiseSVN.
+
# Right click on the new folder and you’ll see some new options for TortoiseSVN.  
 
# Select 'Checkout' and use the following path for the 'URL of Repository'...
 
# Select 'Checkout' and use the following path for the 'URL of Repository'...
  
 
  {{svn_trunk}}
 
  {{svn_trunk}}
 +
 +
===== Alternate update method for TortoiseSVN v1.4.4 =====
 +
# Follow steps one and two above, if you haven't already.
 +
# Right click the source folder you created in step two and select TortoiseSVN -> Repo-Browser
 +
# Enter the following path into the Repo-Browser dialogue:<br><br>{{svn_trunk}}<br><br>
 +
# Right-click "trunk" and select "checkout..."
 +
# In the 'checkout directory' field, browse to the source folder you created in step two.
 +
# Hit OK and wait a bit for the files to be downloaded (at the time of this writing, the trunk folder was in the neighborhood of 68 megs.
  
 
===== Updating Your Source Folder =====
 
===== Updating Your Source Folder =====
Line 84: Line 92:
 
# Isolate Work, Not People
 
# Isolate Work, Not People
 
# Remember Thermodynamics!
 
# Remember Thermodynamics!
 +
 +
== Links ==
 +
*[http://svnbook.red-bean.com/ ''Version Control with Subversion'', eBook by O'Reilly]
 +
 +
[[Category:Developer resources]]

Latest revision as of 12:19, 19 July 2009

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

[edit] Setup

[edit] Linux Setup

[edit] Overview

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

[edit] 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.

[edit] 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

[edit] 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.

[edit] Graphical User Interface (SVN Approach)

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

[edit] 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

[edit] 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

[edit] 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.

[edit] The Process

[edit] 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. If you're using version 1.4.4 (the latest, as of 7/10/07) of TortoiseSVN, please skip down to the alternate update method below.
  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
[edit] Alternate update method for TortoiseSVN v1.4.4
  1. Follow steps one and two above, if you haven't already.
  2. Right click the source folder you created in step two and select TortoiseSVN -> Repo-Browser
  3. Enter the following path into the Repo-Browser dialogue:

    http://svn.openmoko.org/trunk

  4. Right-click "trunk" and select "checkout..."
  5. In the 'checkout directory' field, browse to the source folder you created in step two.
  6. Hit OK and wait a bit for the files to be downloaded (at the time of this writing, the trunk folder was in the neighborhood of 68 megs.
[edit] 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.

[edit] Developement

[edit] 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.

[edit] 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.

[edit] General Advice

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

[edit] Links

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.

Use the wget tool to do it, as follow:

wget -r -np -nH --cut-dirs=1 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!