As of the 2.0 release, Sakai uses Subversion for all of its source management needs. (CVS was used for 2.0 and earlier releases.)
Subversion is an open source project (http://subversion.tigris.org/
), in development since 2000, which has produced a new version control system that is very similar to CVS, but which addresses many problems and annoyances with that system.
Clients for accessing subversion (abbreviated svn) repositories are available for all modern flavors of Unix, MacOS X, Win32, BeOS, and OS/2. Other software, such as emacs and eclipse, which currently have ways of accessing CVS repositories also now have similar access to CVS, or such functionality is generally under development.
Resources:
Additional Sakai source control information is available in:
Sakai Subversion Conventions
Before checking any changes into the Sakai svn repository, please become familiar with (and start following) the following conventions.
- Always include a meaningful log message. Undocumented source changes may be the biggest mistake possible in a collaborative project. Don't feel embarrassed if you have to repeat a message because you thought you'd fixed something but didn't. People (including you in the future) will still need to understand the point of every single change.
- Bundle functionally-related changes into a single check-in. The point of source control history is to document the fit of tasks to file changes. Tracking those detailed file changes, deciding whether to merge them, and deciding how to package them all become much easier if completed tasks are checked in as a unit.
- Don't bundle unrelated changes into a single check-in. If a change needs to be merged into, say, a maintenance branch then having to pick apart a single commit with mulitple changes makes the job far harder.
- Cross-reference svn log messages with JIRA IDs. In almost all circumstances, if you're checking code into a released project your svn log message should start with a JIRA ID followed by a space. (For example, "SAK-4117 Need to guard against zero-point assessments to prevent divide-by-zero exceptions".) This will let the production release manager and others know where to go to find out more about the task. The only exceptions I know of are incremental check-ins related to a new project or major new functionality. But if you're checking into the trunk, always try to get a JIRA cross-reference, even if you have to create the related JIRA task yourself.
- Cross-reference JIRA resolutions with svn revision numbers. After svn has finished including your changes in the repository, it will show you the unique revision number associated with that check-in. In JIRA, you should never mark a task, feature request, or bug as resolved and pass it on to your QA process without mentioning which revision finished the task. (For exampe, "Fix checked in as revision 6624.")
- Don't break the build! Don't check in any changes to the trunk unless you're completely confident that they won't stop a vanilla Sakai build. (And yes, a "vanilla Sakai build" includes any automatic JUnit tests.
)
Sakai Subversion Configuration File - Glenn Golden
When you are committing to Sakai SVN space, you should have the sakai SVN config file installed on your machine. This will help keep our files consistent in the archive.
The file is located here:
https://source.sakaiproject.org/svn/trunk/svn/config
Install it as a file called "config" in your user's home space ~/.subversion directory, or, to quote the message in the top of this file:
### Copy this file to ~/.subversion/config (Unix) or "%APPDATA% \Subversion\config" (Windows)
Recently files were checked in without the proper properties, such as those that cause keyword expansion. I think this may be due to missing the proper SVN configuration file.
Subversion in Sakai 2.2
Don't Work on Tags! - Glenn Golden
While you can checkout the 2.2.001 tag, it is vital that you do not attempt to do an work on this code. If you do, and check it in, you will be checking in against a TAG, not against a working trunk or branch.
In the past, you would not have been permitted to do this, but since each development team has access to all their trunk, branches and tags, now you can.
Please do not.
As you make changes from 2.2.001 in the direction of our final release, make them to your trunk. The easiest way to setup for this is to checkout the sakai trunk:
svn co https://source.sakaiproject.org/svn/sakai/trunk sakai
At some point, a project may decide it needs to make a branch for further 2.2.x work. Then work for that project will need to be done in their trunk and their branch as appropriate, and further 2.2-00x tags made from their branch.
Actually, it might be easier at this point in the development cycle to make a branch for future work, and leave the 2.2 effort in your trunks until we cut the final tags for the release.
The new SVN structure gives each development team greater powers. With that, please exercise greater care.
Tips from Jim Dougherty
I'll add some general advice here on Subversion.
- Read "the Subversion Book" available on the web. Its well written, free
with good examples and important to understanding the repository
organization and commands.
- Set up your own repository ... this is required if you want to control
the patching by doing merges with vendor drops.
- I find Tortoise takes some of the drudgery out of the CLI. The
integrated repo-browser is nice, and the confict resolver functionality is
not offered with the CLI....
- I think the trick to the vendor drop process is to maintain your own
exports of sakai tagged releases in a /vendor directory you make in your own
repository. Build your first system based on a given sakai tagged release.
Make your local changes and commit them always to your repository.
When you are ready to 'update' with the latest from sakai.. 1. take an export of the sakai version you want to upgrade to and store it in the vendor area of your own repository. e.g. /vendor/sakai/sakai_2-2-2 Checkout trunk from your own repository. Then use the svn merge command specifying to apply changes between vendor drop -1 and vendor drop. ( I always use -ignore inheritance switch here ) The difference between those two vendor drops are then applied to your working copy. You'll now need to resolve conflicts, if any. Then commit to your repository, export and rebuild.
Committing Code
Before you can commit code to the Sakai subversion server, you need to have commit access to the code you want to change (or add). The subversion server is currently administered by Indiana University. You can get information about SVN access by sending mail to svn@collab.sakaiproject.org 
. The people at this address can also help you determine who has commit access to the area you need to change or extend.
SVN long longer requires any certificates or SSH to set up. You may have to tell your svn client to accept the self-signed HTTPS certificate the first time you connect, but thats it. Authentication is done via user names and passwords. If you don't have an account on the subversion server, send mail to the svn email address given above.
Posted by
Added an additional convention: don't bundle unrelated changes into a single check-in.