Sublime Subversion

Over the last couple of days we have started posting some short tutorial videos. Initially these videos focus on how to use Sublime but over time we will expand the scope to cover Subversion topics as well.

• Tutorial 1: Creating Subversion Repositories in Sublime
• Tutorial 2: Checking out a Repository

Please let us know if these videos are helpful and if you have any suggestions on features to cover or ways we can improve them.

Apologies for the radio silence recently.  While finishing up Sublime 1.1 we decided to completely re-write the Sublime installer.  We had been using an off-the-shelf product for our installer which worked okay initially.  However, after digging into more of the details we decided to switch to the excellent open-source Wix installer.  While we believe this is a good long term decision, it did add quite a bit of development time to 1.1.  We’re working the last bugs out of the installer now and should have 1.1 released soon.

So what’s new in 1.1?  Well the biggest new feature is RSS Feeds.  With Sublime 1.1, each repository will expose an RSS feed of the commit history.  This can be a great alternative to email-based commit notifications.  Each item in the RSS feed will show the time of the commit, the author, the commit message, and the list of changed files.

In addition to repository RSS feeds we added an RSS feed for administrators.  This feed will contain important information about the server such as the success or failure of repository backups, information about new users or repositories created, etc.

We’ve been using both of these features on our internal servers for a couple of months and really like them.  Hopefully you will two.

In addition to those features we’ve included a number of minor enhancements and bugfixes including:

• Turn On/Off Repository folder hierarchy.  This allows administrators to specify whether repositories will be created in a folder hierarchy or a flat list.
• Better support for non-English Subversion servers
• UI bug fixes including better paging support for repositories with a large number of commits
• Email notifications enabled by default for new repositories

Thanks to all of you who have sent us feedback and suggestions.  Once 1.1 is released we’ll post our plans for 1.2.  Remember, 1.x releases of Sublime are free upgrades to anybody who has purchased a Sublime license.

The Sublime Service Account is used to run the Sublime web application.  You define the account when first installing Sublime.  To change this account, execute the following steps on your Sublime server:

1. Add the new service account to the local Administrator’s group
2. Add the new service account to the local IIS Worker Process group (IIS_WPG for Windows Server 2003, IIS_USRS for Windows Server 2008).
3. Change the Identity of the SublimeAppPool application pool
   • Open the Internet Information Services (IIS) Manager from Administrative Tools
   • Expand the Application Pools folder, right-click SublimeAppPool and choose Properties
   • Click the Identity tab
   • Enter the username and password for the new service account
   • Click OK
4. Recycle the SublimeAppPool application pool, or perform an IIS Reset.

Over the coming months we will be releasing the roadmap for Sublime. This will include new features and updates for version 1.0 (which are available free to all current 1.0 users) as well as future plans. To make sure we are planning the right features for Sublime we have set up a user forum to capture your feedback and ideas. Here you can vote on ideas submitted by other users, or submit your own suggestions.

Currently the top contenders are:

• SharePoint integration – creating a repository will create or connect to a SharePoint project site
• Repository History RSS feed – expose an RSS feed on repository commits – may be used as an alternative to email announcements
• Path-based permissions – allow permissions to be set on paths within a repository
• Active Directory Groups – allow AD security groups to be used when assigning permissions

There are plenty of other ideas as well ranging from an enhanced repository browser, incremental backups, and security/permission audit.

Please help us make Sublime the best Subversion server available by providing your input and ideas!

Sublime will automatically send email notifications to your developers after a commit is made.  You can enable email notifications for your repositories by navigating to the Repository in Sublime, clicking the Edit Settings link, and changing the Email Notification setting to “On”.

By default, each email notification looks like this:

Default subversion email notification

However, this can be customized by editing an HTML template file located on your Sublime subversion server.

1. Connect to your server using Remote Desktop
2. Locate the “bin” folder inside your Sublime installation directory (C:\Program Files\Sublime\bin by default).
3. Make a backup copy of the file “EmailTemplate.htm”.  This is optional, but recommended so that you will be able to revert to the default template if you wish.
4. Now, using a text editor such as notepad, open “EmailTemplate.htm”.
5. Modify the HTML to customize the body of the email message.  When Sublime sends an email notification, it replaces certain placeholder tokens in the email template with actual commit details.  For example, “{REPOS}” is replaced with the name of the repository.  A complete list of placeholder tokens is listed below.
6. Save “EmailTemplate.htm”.

Here’s an example of a customized email template.  We have added our company logo at the top, and excluded some of the commit details.

Customized email notification

Placeholder Token Reference

The table below contains the complete list of placeholder tokens which may be used in your email notification template. The example for each is taken from the screen shot below the table so you can see exactly where the token is used in the email notification.

Default subversion email notification

Sublime automatically backs up all of your Subversion repositories on a schedule you define.  In this short article we will walk through the process of configuring your backups, monitoring your server to ensure backups are happening, and restoring a repository.

1. Configuring Backups

To configure your backups, navigate to the Administration section in Sublime and click the “Backups” tab.  First, enter a path for your repositories to be backed up to.  When you install Sublime, it will default this path to be a Backup folder within your Sublime installation directory.  However, it is strongly recommended that you back your repositories up to a network device such as a NAS or remote network share.

Next, enter a time of day and the days of the week that your backups should occur.  Generally this should be a time of the day that users are not using Subversion.  However, Sublime uses the subversion “hotcopy” command when making backups so even if your users are still accessing Subversion you are not at risk of corrupting data or interrupting the backups.

Lastly, enter a backup account to be used when performing the backups.  This account must have read/write access to the Backup path.  It will also be added to the local administrators group on your subversion server.

Scheduling subversion backups in Sublime

2. Monitoring Backups

Each time Sublime backs up your Subversion repositories, it will write an entry to the Windows Event Log.  You can monitor this directly from the Sublime web interface, or by connecting to the server using remote desktop.  Each entry in the windows event log will list the number of repositories backed up, the number of errors (if any), and the duration for the backup.

Successful Subversion backup in the Windows Event Log

If you are using Windows Server 2008, you can create a Custom View to show only Subversion backup messages.  Simply create a new Custom View to display “Information” events filtered where the Source is “Sublime.SubMaint”.

3. Restoring a Subversion Repository

Restoring a repository is essentially copying the backup repository from the backup location back to your Subversion server.  However, as a best practice we recommend the following steps:

1. Take your Subversion service offline.  This ensures that while the restore is underway, your developers cannot commit to the repository.  If you are running Sublime in SVNSERVE mode you can take the Subversion service offline from the administration home page.  If you are using Apache you will have to stop the service manually in the Services console in Windows.
2. Locate the folder containing the repository you want to restore on both your Subversion server, and in the backup location.  The backup location should be a mirror of your repositories folder on your Subversion server, so locating the correct repository should be easy (see below for tips on identifying a repository folder).
3. On your subversion server, delete or rename the folder containing the repository you want to restore.  Then, copy the repository folder from the backup location over to your subversion server.

Let’s look at an example.  In the screen shot below, the left folder is the Repositories folder on our Subversion server.  This contains all of our current “live” repositories.  The folder on the right is our backup location.  If we wanted to restore the “CommonLibs” repository, first we would delete “CommonLibs” from the “Archive” folder on the left.  Then we would copy the “CommonLibs” folder from the backup location on the right and paste it in the “Archive” folder on the left.  The result would be a fully restored version of the “CommonLibs” repository from the time the last backup ran.

The Backup location is a mirror of your Repository location

Once you have restored your repository you can bring the Subversion service back online.  It is also a good idea to reset IIS (open a command prompt and type “iisreset”) to ensure that the Sublime cache is cleared.

TIP: How to locate a repository folder

If you are new to Subversion it may not be clear exactly what constitutes a repository.  In short, a repository consists of a folder containing a number of specific sub-folders and files.  So when we say “repository” we are talking about the parent folder and all child folders and files.

You can identify the repository parent folder by looking at its children.  A repository will contain the following child folders: conf, db, hooks, locks.  It will also contain a file called “format” and there may or may not be a README.txt.  In the following screen shot, we are looking at the content of “CommonLib”  You can see that it contains these folders, thus “CommonLib” is a repository.  The parent folder “Archive” is not – it’s merely a folder.

Identifying a repository folder

Repository Templates are a great way to reduce the time required for setting up a new project, and encourage consistency across projects.  Consistency is important especially in an organization with many different repositories spread over different projects and development teams.  Having a consistent repository structure drastically reduces common errors made by new developers or even experienced developers in an unfamiliar repository.

Setting up Repository Templates in Sublime is as easy as creating a folder structure on your Sublime server containing the files and folders you want to include in your new project.  In this walk-through we’re going to create a Repository Template for new projects using Sharp Architecture.  Sharp Architecture is a perfect candidate for a Repository Template because there are quite a few dependencies that can take a while to download and organize.

In the following steps we’ll be creating a Repository Template for Sharp Architecture, but the same steps can be applied to any number of project types you may have.

1. Create the new Repository Template Folder

The first step is to create the new Repository Template folder on your Sublime/Subversion server.

1. Connect to your server using Remote Desktop
2. Navigate to the “Templates” folder beneath your Sublime install location (typically C:\Program Files\Sublime\Templates)
3. Create a new folder inside Templates called “SharpArch” (note: the folder name can be different from what your users see when choosing a template)
   

   Create a new folder for the template

4. Open the new folder and create the standard Subversion trunk, branches, and tags folders.
   

   Create the branches, tags, and trunk folder

5. Open the “trunk” folder you just created.  Now it’s time to start creating the folder structure for your new project.  For starters, Sharp Architecture projects tend to have a defined top-level folder structures for the different elements of a project: app, build, db, tests, etc.  So let’s create those folders now.
   

   Create the project folder structure

6. Next, if you like you can create README.txt files in each folder explaining what should be placed there.  This is optional of course but can be useful for new developers who may not be familiar with the project structure.

2. Download Sharp Architecture binaries

Now that our basic structure has been created, it’s time to download the related Sharp Architecture binaries as well as their dependencies.

1. Open a web browser and navigate to the Sharp Architecture download page.
2. Download and extract the latest revision (or which ever revision you prefer) of the compiled binaries
3. In the extracted folder, locate all of the DLLs and associated files (located within the “bin” folder as of this writing) and copy them all to the “lib” folder we created back in step 5 of the previous section.
   

   Copy Sharp Architecture binaries to template

3. Register the Template with Sublime

The last step is to register the newly created Repository Template with Sublime.

1. Navigate back to the Templates folder and open “templates.txt” in Notepad
2. This file follows a simple INI file format and you should have two templates already listed (Standard and Empty).  Create a new section with the following structure:
   [SharpArch]
name = Sharp Architecture
description = Use for Sharp Architecture based projects.
   

   Insert new template description into templates.txt

3. In the example above, the section header “[SharpArch]” must be the same as the folder name for the template.  But the value for the “name” attribute is what will be displayed to your users.  There is also an optional “default = true” attribute you can add if you want this template to be automatically selected as the default choice when creating new repositories.
4. Save templates.txt and close Notepad.
5. Next you must restart IIS by opening a command prompt and typing
   C:\> iisreset

4. Test the Template

Open a web browser and navigate to Sublime.  Click on the Create New Repository tab and in the Template section, you should see the new “Sharp Architecture” template.

Preview the new template

Wrap-up

In this walkthrough we’ve created a new Repository template for projects using the Sharp Architecture framework.  We created a folder structure and pre-downloaded all binaries and their dependencies so that new repositories would automatically have this structure and these resources.  This same approach could be taken for any number of project types relevant to your organization.

Using these same techniques you could make your template more robust including common resources such as:

• NANT build script templates
• Visual Studio .sln or .csproj files (although your users would most likely have to re-name them for your project)
• Common scripts or tools used by your organization
• Default config files with references to your development or production environment
• etc

For additional information and complete documentation on creating Repository Templates, please see the Sublime documentation.

This is just a friendly reminder that beta versions of Sublime are no longer valid.  If you are running Sublime 0.6 or lower, you may receive the following error message:

The license for this Sublime server has expired.  Please contact support@pico-logic.com to extend your license or receive an upgrade.

If you are running version 0.7, you will see a warning that the license is expired and you might not be able to create new repositories or users.

If you are still running the Sublime beta and need additional evaluation time, please contact info@sublimesvn.com to receive an extended beta license key which will expire on 10/1/2009.

It is with great pleasure that we announce the release of Sublime 1.0. To celebrate our release we are offering an introductory discount of 30% off of the full retail price. To purchase Sublime licenses or get additional details, please see the Sublime Licensing page.

I would like to personally thank all of our beta testers. Without your feedback, bug reports, and suggestions, Sublime would not be as robust as it is today.

Over the course of the beta, many people have asked about Sublime licensing. You can see the full details on the Sublime Licensing page, but here is a brief summary.

• Sublime is licensed on a per-user basis. Each user accessing Sublime and Subversion repositories managed by Sublime requires a user license.
• Sublime ships with one free user license so Sublime is completely free for individual use.
• Email-based technical support is included
• You are eligible to receive all future updates to version 1.0 absolutely free.

Please see the Sublime Licensing page for specific licensing costs and to purchase your licenses.

Moving forward we will continue to refine and improve Sublime. In the coming months we will publish a Sublime roadmap describing the future changes and additions we plan to make to the product. However, we cannot improve Sublime in a vacuum. We need your input and feedback! Please let us know if there are features you would like us to include, Subversion configurations Sublime should support, or other ideas for improvements. I believe that Sublime is simply the best management tool for Subversion available today, but with your ideas and feedback, it can be even better.

As we approach the release of Sublime 1.0 (expected very shortly) some of you may be concerned that your beta version will be expiring at the end of this month. If you are running version 0.7 after 9/1/2009, you will no longer be able to create repositories or users. If you are running a version earlier than 0.7, it will stop working all together.

Starting today, we will be offering extended beta licenses for anybody who would like a little more time before their beta expires. This is intended for organizations who need a little more time evaluating Sublime, or who’s buying process may take longer than a couple of weeks.

To get your extended beta license, simply send an email to info@sublimesvn.com requesting a new license. The extended beta license will allow you to continue to use Sublime free of charge until 10/1/2009.