Getting the Code from Source Control
The GI 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.
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.
Browsing the Repository
You may browser our subversion repository (http://svn.dojotoolkit.org/src/) directly using a web browser or browse using the Bug tracker.
Directory Structure
The code is structured with each subproject (dojo, dijit, dojox, util) as a separate directory. Within each subproject you will find the "trunk" as well as "branches" and "tags". You may pull these subprojects separately, or use a special svn "view" which links the subprojects and checks them out with a single command.
Note that the "trunk" directory at the top-level is obsolete. This was used prior to the 0.9 release, when the code was reorganized into the various subprojects.
To do an anonymous, read-only checkout of the Dojo development trunk:
svn co http://svn.dojotoolkit.org/src/view/anon/all/trunk dojotoolkit
Or, to pull a particular release, such as Dojo 1.0.2:
svn co http://svn.dojotoolkit.org/src/tags/release-1.0.2dojo102
Branches in the GI Repository
Most GI development takes place on the trunk. Branches may be used for development of experimental features or for code migration before being merged back into the trunk. Branches are also used to stabilize major releases.
Making Changes to the Repository
Anyone may access the Dojo Subversion server. Contributors are encouraged to access code directly from the repository and submit patches using the bug tracker. To submit changes, however, you must have committer status and have already received a system account from the administrator.
To access the repository as a committer, use this URL with subversion:
svn co --username=YOURUSERNAMEhttps://svn.dojotoolkit.org/src/view/committer/all/trunk dojotoolkit