Sublime Subversion

This is the first post in a series on what’s new in Sublime 1.2. Version 1.2 will be released next month but we’re so excited about the new features that we wanted to get the word out now.

First up: Path-based permissions.

This feature has been requested for some time and is finally making its way into Sublime. In 1.2 a repository owner will be able define unique permissions at different paths within a repository. A common scenario may be to allow all developers read/write access to the trunk, but then lock down the branches or tags folders to lead developers or release managers.

Below, we can see the updated Permission Management interface in Sublime 1.2. On the left we see the repository structure and the red icon overlay indicates that a folder has unique permissions applied. Clicking on that folder we can see, and then manage permissions for that level in the repository.

Assigning path-based permissions in Sublime

If you make a mistake and would like to remove all unique permissions you can simply click the “Remove these permissions” link in the highlighted area to the right.

Well that’s it for this update. For our next Sublime 1.2 Preview article we will discuss the new personalized Dashboard.

We’ve been working away here on Sublime 1.2 and have a few interesting features to share with you.

First, we’re going to be offering better support for managing your repository organization from within the Sublime web interface. For example, admins will be able to create folders directly within the web interface instead of having to create them from the server.

Second, we’re expanding our RSS support by creating a “My Repositories” feed. This feed will include commit messages to any repository that the subscriber is a committer for making it easy to subscribe to a single feed and automatically stay up to date across all of your projects. We’ll also be allowing RSS feeds to be accessed anonymously (admin configurable) so that they can be accessed easier from external RSS readers or readers that don’t support authentication.

Lastly, we’re expanding the Repository Template functionality to scan your templates for certain tokens and replace them with repository-specific information. For example, if your template includes a visual studio .sln file, you can name this file %name%.sln and it will automatically be renamed with the name of the repository. This works within the contents of your files as well allowing you to set up complete boilerplate project structures.

We always felt that while very useful, templates always came up a little short in truly jump-starting a project because they couldn’t customize the template to the project at hand. We feel that this update will close this gap and provide a significant productivity improvement for Sublime users.

We’ll be posting more on this feature in the future including a full tutorial on how to create repository templates that leverage this functionality.

Stay tuned for more updates on 1.2. We’ve got plenty of other features and improvements we’re adding including:

• My Repositories view
• Significant performance improvements
• Filtered views for the repository browser
• Active Directory Security Group support
• and more…

We have just uploaded our latest tutorial video for Sublime. This video covers subscribing to Subversion Repository RSS Feeds.

As always, please send us your feedback about these videos, or suggest other topics you would like us to cover.

We are planning to release tutorial videos for the following topics next:

• Managing Repository Permissions
• Configuring Sublime with LDAP Authentication
• Creating and Managing Repository Templates

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.

Sublime 1.1 has been released and is available for download now!  Current users of Sublime 1.0 can download 1.1 and upgrade their server for free.  Please see the upgrade instructions for details on upgrading your server.

Below are the new features added in Sublime 1.1:

• Repository RSS Feeds
  Each repository exposes an RSS feed for repository commits.  Repository RSS feeds contain the same information included in repository email notifications such as commit message, date, changes, and author.
• Event Log RSS Feed
  For server administrators, the Sublime event log is now exposed as an RSS feed. This allows administrators to see errors or backup notifications as they occur without having to check the event log or Sublime web interface.
• Disable Repository Folders
  If you do not plan on organizing repositories into folders, or your Subversion server doesn’t support a folder structure (i.e. Apache) you may now disable repository folders in the Sublime interface.  When disabled, the repository list page will no longer display the folder hierarchy, and users won’t be prompted to choose a folder when creating new repositories.
• Support for SMTP Servers requiring SSL (e.g. Google Apps)
  When configuring email settings for the server, administrators can specify that the server requires a secure connection.  This is required for some email servers such as Google Apps.

For a complete list of changes and bug fixes in 1.1, please see the release notes.

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.

Even if you are new to Subversion you have likely heard terms like “trunk”, “branching” and “tags” thrown around.  If you are coming from a source control system like CVS you may already be familiar with these terms but if you are coming from a tool like Visual Source safe they may be new.  This post provides an introduction to these concepts in Subversion.  For more in-depth information please see Chapter 4 of the Subversion Book.

First things first – the trunk.  In Subversion, the term trunk refers to your main source code tree.  If you are starting out a new project, you will spend the majority of your time making changes and committing them to the trunk of your repository.  This is because early in a project there are fewer situations where you need branches or tags (there are certainly exceptions depending on your team and development practice, but this is an introductory article and we won’t get into that).

Now, let’s say your project is moving along and getting fairly stable, but you want to experiment with adding a new feature.  You could simply start making changes in your working copy and see how they work out without ever committing them, but this would be a mistake.  If this is a large set of changes your work could span multiple days – even weeks.  At some point your manager is going to wander over to your desk and inform you that there is a critical change that needs to be made RIGHT NOW. Now you’ll need to set aside those experimental changes, get a fresh copy of the trunk, commit those, somehow port those changes into your experimental code, etc etc.  It gets complicated fast.

Branching is specifically designed for situations like this.  A branch is a copy of your source code – typically a copy of the trunk – with a special name like “experimental feature”.  It sets up a space for you to work and make changes without committing to the main trunk.  Once the code in your branch is complete, you can merge your changes back to the trunk.  In addition, as new changes are committed to the main trunk, you can merge those changes into your branch so your branch is up to date with the latest changes from the trunk.  This is a great habit to get into by the way because it makes the process of merging your branch back to the trunk much much easier when the time comes.  Not to mention the fact that you are much more likely to catch potential integration issues early.

I’ll come back to branching in a bit, but now let’s move to tagging.

A tag is simply a named version of your code at a particular point in time.  For example, let’s say you’ve reached version 1.0 of your project.  Rather than having to remember that version 1.0 was revision 638, you can create a tag and give it the name of “1.0″.  Best practice is to create a tag for every major release or milestone (beta, 1.0, 1.1, 2.0, etc) but you can create tags for any point in time you think developers will care about in the future.

So we’ve covered the basic concepts, now I’m going to let you in on a little secret.  Ready?  In Subversion, there is literally nothing special about a branch, or a tag, or the trunk for that matter.  It’s just a directory in your repository which holds a version of your source code.  That’s it.  In most Subversion repositories the directory for storing branches is called, well “branches”, but that is just a naming convention.  You could call yours “superman” and Subversion would still behave exactly the same.

Here’s what I mean.  Most repositories will have the following structure at their root:
/branches
/tags
/trunkEach path above is simply a directory in your repository.  Trunk is self explanatory – it contains your main development tree.  Branches is a folder which will contain sub-folders, one for each branch.  Tags is the same – a folder which will contain sub-folders for each tag.

Here’s what your repository might look like with several tags and branches:

/branches
/branches/new_feature <- branch for implementing a new feature
/branches/1.0_maint <- branch for doing maintenance on version 1.0
/tags
/tags/0.9 <- version 0.9 release
/tags/1.0 <- version 1.0 release
/trunkWhen you create a branch, or a tag, Subversion is simply copying your current code usually from the trunk (although not required) into a new folder in /branches or /tags. Once your code is copied, you can check out a new working copy from that location, make changes, commit, etc. Since your working copy points at the branch folder rather than the trunk, changes you make will only be committed to the branch and not to the trunk. The act of merging is essentially picking the changes you have made and moving them back into the trunk. Subversion gives us tools to make this easier, but it essentially boils down to just that.

Now, why is this important? Well for one it means you aren’t stuck with the standard naming convention of branches, tags, and trunk. If you prefer something like “variations”, “labels”, and “root” it is entirely up to you – Subversion won’t care. However, unless you have a compelling reason to change, it’s best to stick with branches, tags, and trunk because it is widely accepted as the standard naming convention.

Another reason this is important is that Subversion isn’t going to limit you from making mistakes like checking out a tag and making changes to it. Making changes to a tag goes against the entire purpose of a tag because a tag should be a static point in the history of your code – not something you make changes to. If you need to make changes to version 1.0 outside of your trunk (maintenance for example) you should make a new branch using your 1.0 tag as the source (step by step instructions is beyond the scope of this article).

So that’s it. Branches, tags, and trunk are simply standard folders in your repository set up to help you manage your development process. You can change these conventions if you wish, but you should have a solid reason for doing so. You can also add to this structure if you need additional controls for your development team or process.

Before closing I want to make one point about how your code is copied to a branch or a tag. Subversion is smart enough not to make an entire duplicate copy of your code each time you create a branch or tag. It simply creates a pointer to the revision your branch is based on. When you make a commit to the branch, Subversion stores the difference between the modified version and the original file. It does not create a full copy of the file.

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