The Dojo team uses Subversion for source control. Those familiar with CVS will find the command line syntax for subversion to be very similar. Regardless, the following instructions are geared to those not familiar with CVS, or even source control in general.

Authoritative documentation on Subversion is available here.

Why Source Control?:

Source control is one of those things that one rarely notices they need until it's far too late, usually when you accidentally delete part of your source tree instead of simply moving it to a different location, or when you make a set of complex changes that leave you worse off than were you started (but you can't go back). A source control system solves these problems by keeping copies of each revision of a set of files on a server, while giving you access to a local copy of those files to make changes on. Good source control systems allow multiple people to modify a single file at once, and will try to automatically merge changes between differing sets of modifications. A good source control system will also let you browse the history of a file or set of files (allowing you to "go back in time") and allow you to have acccess to your code from as many systems as you like. Subversion is one of those good source control systems.

General Information:

Across the gamut of source control systems, there is quite a bit of confusing (and non-portable) nomenclature surrounding the common actions that you as a developer will preform with the source control system. We will use the terms here that are commonly accepted by CVS and Subversion users and administrators. So what are those terms?

• Checkout: a "checkout" is a local working copy of a "repository". This is the set of files that you will be working with when making modifications to Dojo.
• Repository: the logical grouping of project-related files on the server. A subversion server may host multiple repositories, but it is quite likely that your changes will be constrained to a single repository.
• Checkin: transmitting a set of changes from your local checkout to the server. Your changes will then be available to everyone else who has a checkout of that repository when they update their view.
• Head: (also called the "main line") the most up-to-date version of the source control tree. Most of your checkins will be to the "head" of the tree, although in some more complex situations, you may be checking in to a "branch".
• Branch: A clone of the source control repository from some point in time which contains a set of changes which are not shared with the "head" or main line. Branches are one way for a developer to work on a particular feature (usually a large feature) and have intermediate changes versioned without having to worry about whether or not his or her changes will break someone else's code. Changes can then be "merged" back back to the main line when the developer thinks they are stable.
• Merge: merging is the process of taking several versions of a single file and turning them into one authoritative version. Merging in is often an automated process with Subversion, but you may at times be called upon to merge a set of files manually (when the server cannot automatically take care of it).

Unlike some other source control systems, Subversion manages files on your disk without interjecting itself obtrusively into your workflow. You can change large sets of files
without worrying if anyone else is also modifying those files.

Getting Access:

In order to access the Dojo Subversion server, you must have already received a system account from the administrator. If you have not done this yet, please contact Alex Russell <alex@dojotoolkit.org>. Once your system account is created, please test your account by logging in over SSH. The Dojo team uses SSH (the Secure Shell) to encrypt access to our source control system because Unsecure Network Logins Suck (TM).

Anonymous Access:

To anonymously access our subversion repository you can use a web browser (http://svn.dojotoolkit.org/dojo/trunk/).
Or check out anonymously:

svn co http://svn.dojotoolkit.org/dojo/trunk/

Setup for Windows:

If you use Eclipse, then perhaps use the subclipse plugin (I have heard it is better than TortoiseSVN?).

To access our subversion repository on Windows, please install TortoiseSVN, available at: http://tortoisesvn.tigris.org/

Installing Tortoise requires a reboot since it installs itself as a Windows Explorer shell extension.

Welcome back!

Now that you have rebooted, open up a Windows Explorer window (Win-E, or right-click on the "Start" menu and select "Explore"), navigate to whatever directory you would like your Dojo source code to be placed under. Create a new directory there titled "dojo", and then navigate to it. Once inside the directory, right click on the emply file list and select TortoiseSVN->Settings. In the resulting dialogue box, got to the "Network" tab.

Using TortoiseSVN? with ssh is a right pain because it repeatedly asks for the password again and again. If you can use an anonymous checkout that may be better.

NOTE: in the latest version (1.3.3) leaving the ssh client field blank worked, and setting it to TortoisePlink?.exe didn't (Even in double quotes). Previously: As of version 1.1.x, you must manually configure Tortoise to be aware of it's SSH client program, which is usually located in:

C:\Program Files\TortoiseSVN\bin\TortoisePlink.exe

Use the "Browse..." button at the bottom of the "Network" tab in order to locate and select "TortoisePlink.exe". With that done, you can hit "OK" in the configuration tab and return to the "dojo" directory we created earlier.

Right-click in the directory and select "SVN Checkout..." from the context menu. In the resulting dialog box, you will be prompted for a URL for the repository you want to check out. Subversion supports multiple access methods, but we will use Subversion over SSH to get to our repo. In this dialog box, place the following URL (replacing your unix system login for "username"):

svn+ssh://username@svn.dojotoolkit.org/var/src/dojo

Or if you just want to get the trunk (most likely):

svn+ssh://username@svn.dojotoolkit.org/var/src/dojo/trunk

Click "ok" in the dialog box if a dialog box comes up discussing a host key. You will then be asked (two or three times) for your unix user login password at dojotoolkit.org. Provide it. You will then see a list of files being retreived from the server, and when it's finished, you will have your very own checkout!

Next, take a minute to update your svn config settings.

You can then check in your changes by right-clicking on the file(s) you want to check in, selecting providing a checkin comment (strongly encouraged). Other operations, including diffing and merging are also available from the context menu.

For more information about TortiseSVN or how to use it, see the documentation at:

http://tortoisesvn.tigris.org/docs/TortoiseSVN_en/index.html

Setup for Linux:

Since you're running Linux, it is assumed that you're comfy with your systems package management system and the command line.

Firstly, you will need to install an SSH client (preferably OpenSSH) and a Subversion client library (through apt, yast, or whatever package management system your system supports).

Making a checkout is straightforward from the command line. Provided you already have Subversion installed, simply run:

svn co svn+ssh://username@svn.dojotoolkit.org/var/src/dojo

Next, take a minute to update your svn config settings.

This will create a local copy ("checkout") of the source tree (under a new directory called "dojo") in the current directory. Make edits to the files you want to change, then commit them back to the repository with:

svn commit -m "Commit message here" names/of/files

Setup for OS X:

We assume that you are on OS 10.3 (Panther).

Developers on OS X may already have an SSH client installed, but may need to install the Developer Tools package in order to get the most up-to-date JDK and Ant packages. It is assumed that operations will be preformed at the command line, and Project Builder/XCode configuration is not covered here. It is, however, recommended that you download the latest set of developer tools from http://connect.apple.com (free registration required).

Once you have the OS X developer tools installed, download the latest 1.x Subversion package (1.1.3 as of this writing) from:
http://metissian.com/projects/macosx/subversion/

The downloads are an OS X installer package. Install it, at which point the instructions from the Linux section will be sufficient to get you up and running.

SVN Config Settings:

You'll need to add a couple config settings to your SVN config file. If you are on Windows, that's located at:

C:\Documents and Settings\YourUserName\Application Data\Subversion\config

And on UNIX/Mac OS X:

~/.subversion/config

Open it up in your favorite text editor. Most configs have some default settings, so locate [miscellany] and enable-auto-props in the file. If they exist, make sure that they are uncommented (remove # from beginning of line), otherwise add them. They line should look like:

[miscellany]
enable-auto-props = yes

Next, located [auto-props]. If it doesn't exist, add it, otherwise you'll probably have to uncomment it. Add the following entries below [auto-props]:

*.js = svn:eol-style=native
*.htm = svn:eol-style=native
*.html = svn:eol-style=native
*.svg = svn:eol-style=native
*.txt = svn:eol-style=native
*.xml = svn:eol-style=native
*.css = svn:eol-style=native
*.rest = svn:eol-style=native
Makefile = svn:eol-style=native
README = svn:eol-style=native
CHANGELOG = svn:eol-style=native
LICENSE = svn:eol-style=native

Save that and you should be set! Continue on to committing directions above.