Why You'll Love Branches in Escher 0.9.2

As promised, this is the first in a series of posts discussing new features available in the just-released Escher CMS 0.9.2. I’ve decided to begin with the signature feature of this release: Integrated Branch Management.

The Problem: Site Maintenance

I’ve used a fair number of CMS products over the years, and many of them do a pretty good job of easing the site designer’s job of building a new web site, that is, taking a project from conception through design to the actual building and eventual handing off of the site to the client. But this is where most products I’ve used tend to fall over a bit.

Once a site has been handed off to the client and launched, it enters the maintenance phase of its life cycle. And this is where users of typical CMS products begin to encounter difficulties. So, what are the main areas of concern for managing the maintenance stage of a live production site? This is a large topic and there are of course many such areas. But with respect to content management systems, based on my experience I can point to three broad issues:

1. 1. Content Management. The ease with which the client (end user) can add and manage site content.
2. 2. Design Management. The ease with which the developer/designer can change and manage design elements.
3. 3. Role Management. The degree to which the separation of responsibilities between client and designer roles can be enforced.

Let’s take a look at these one by one…

Content Management

As you might expect, most decent CMS products to a pretty good job with content management. That is, after all, what they are primarily designed for! It goes without saying that it should be straight-forward for the client to add new content to the site (pages, articles, posts, images, downloadable files and other media, etc.), edit/remove/categorize content, etc. Ideally, the CMS should also implement some sort of change management, or at least a mechanism to export site content to the file system so that it can be versioned in an external version control system (such as Subversion, Git, Mercurial, etc.) In reality, very few FOSS CMS products offer a change management feature. But otherwise, they do a pretty food job managing content. Escher does not currently support change management for content, but otherwise has a very rich content management feature set. Content management is not the focus of this article, so we’ll leave it at that for now.

Design Management

Unfortunately, most CMS products I have worked with don’t put nearly as much emphasis on easing maintenance chores for site developers/designers. Smaller tasks, such as updating a style sheet, don’t typically cause problems. But more often than not, changing the design means changing several aspects at once, usually involving multiple assets and asset types. For example, a typical design change might involve structural changes to the underlying HTML of one or more pages, CSS changes to one or more style sheets, adding/removing images, JavaScript changes, etc. If the CMS allows for breaking up a site’s markup into multiple components (e.g. Escher’s “snippets”), then there will likely be multiple such components that need to be changed. These are not changes that typically can be made one at a time without affecting the live site. And let’s be clear here. When I say affecting I really mean breaking. So making changes of any complexity usually requires downtime for the site being modified, which is clearly undesirable.

A second aspect of this issue concerns the lack of an easy way to preview new design changes for the client before making them live on the production site. Suppose you roll out your new changes and the client doesn’t like them and asks you to roll them back. Oops. Hope you backed up that database prior to making those changes!

To work around these difficulties, web developers/designers are often forced to resort to some pretty drastic measures involving setting up and maintaining additional development and/or staging servers, maintaining multiple installations of the CMS software, and frequent exporting/importing of database dumps from one to another. These additional server administration duties are likely not what the designer prefers to spend her time on, and may even be beyond her level of technical expertise.

This is the major issue addressed by Escher’s new branching feature, discussed below.

Role Management

Some CMS products do a decent job at separating the responsibilities of the designer (who needs to maintain the design elements of the site) from the client (who needs to add and manage content), although some do much better than others in this respect. Why is this important? Quite simply, it is beneficial for the system to prevent the client from modifying elements of the design (whether intentionally or accidentally) while they are authoring their content. When this happens, the result can range from minor (irritating design inconsistencies between pages or elements on a page) to catastrophic (pages failing to render, etc.) Similarly, the designer should be able to modify an existing site’s design without worrying about accidentally changing or deleting any of the site’s content. Content elements and design elements should be separate and never the twain shall meet! Escher creates a strong distinction between the Designer and Content Editor roles and has a powerful role-based permissions system to back up and enforce that distinction. But again, role management is not the focus of this article, so let’s move on…

Escher’s Solution to Design Maintenance: Branches

A major design goal for Escher CMS is to give web developers/designers the tools they need not only to build great web sites, but also to deploy them and maintain them over time. The 0.9.2 release’s signature new feature, integrated branch management, is designed to solve the design maintenance issues described above. Effortlessly. To learn how it works, read on…

First, let’s re-state the problem.

1. 1. We would like a way to be able to “batch up” a bunch of design changes and take them “live” at once in a single transaction-like operation, thereby avoiding any downtime of our site in the process.
2. 2. We would like to be able to preview these changes, both for ourselves and for the client, before committing them to the live “production” site.
3. 3. We would like to accomplish #1 and #2 without resorting to multiple server and software installations and manual database operations.
   
   

Enter Escher Branch Management

Escher 0.9.2 adds a new design construct to its toolbox: the branch. If you are familiar with version control systems, you can think of an Escher branch as being roughly equivalent to a VCS branch, although somewhat more limited. Basically, Escher maintains three separate versions of your site: Production, Staging and Development. Each of these separate versions is referred to as a branch, and their existence allows us to implement a best-practice development/deployment workflow know as “Develop-Stage-Release.”

Essentially, the workflow goes like this:

1. 1. Develop your site, or most recent set of changes, in the development branch.
2. 2. When you are happy with your changes and you feel they are essentially complete and ready to release, you push your changes to the staging branch. Think of the staging branch as the “nearly ready to go” branch. This is the branch that you present to the client for testing, feedback or approval. If you need to make tweaks, go back to Step 1.
3. 3. Once the staging site has passed all tests and the client approves, you push the staging branch to production. This makes your changes “live” on the production site.

The benefits of the Develop-Stage-Release workflow are clear. You can continue to maintain and change the design of a live site, test changes and preview changes for clients, in an iterative fashion as long as necessary until the changes are ready to deploy – all without ever impacting the live site.

In Escher, you choose which branch is “live” via the Production Status setting in the Basic Preferences pane. So, if you set Production Status to “Development” visitors to your live site will be viewing the development version of your site. I recommend that for any site that has been taken live, you set Production Status to “Production” and leave it there. This will ensure that your production branch is the one that site visitors will always see.

With Production Status set to “Production,” any changes you make to your production branch are immediately reflected in your live site. So making changes to the production branch has exactly the same effect as making changes to your site under previous (non-branch-aware) versions of Escher. Which may leave you wondering, “What’s the point, as this seems to have gained us nothing?” Well, as you may have surmised, once you have taken your site live and set the Production Status to “Production,” you should refrain from making future changes directly to the production branch. Instead, you should start practicing the Develop-Stage-Release workflow. This is where the other branches come in, and the concept of the working branch.

Working Branch

Escher’s working branch, quite simply, is the branch to which future changes will be applied. You set the working branch in the Expert Preferences pane. Once your site is live, I recommend that you set the working branch to “Development” and leave it there. With this configuration, all your future changes will be applied to the development branch. As you make and save your changes, the production branch, and therefore the live site, remain unaffected and continue serving a stable set of pages to your site visitors.

Viewing Your Branches with Auto-Routing

Escher provides a really nifty mechanism for viewing the development and staging branches. In the Expert Preferences pane, you can choose a subdomain name and associate it with the development branch. You can do the same for the staging branch. Set the Enable Development Branch Auto Routing and Enable Staging Branch Auto Routing preferences to Yes. Now, suppose you have chosen “dev” for the development branch host prefix. You can view the development branch of your site by prefixing “dev.” to your site’s hostname in the URL. For example, if your live site is located at http://mysite.com, you can view the development branch at http://dev.mysite.com.

To use the auto-routing feature you will need to do two things:

1. 1. Update your site’s DNS settings to add an A or CNAME record (either will work) for each of the new subdomains.
2. 2. Set up server aliases for the subdomains in your web server’s configuration file.

The specific instructions for these tasks varies by hosting provider. Your hosting provider should be able to help you with this.

Pushing/Deploying Changes

So you’ve been making changes to your development branch, previewing your changes at your development subdomain, and you are ready to push your changes to the staging branch. Escher makes this as easy as a button click (or two). You’ll find a new Branches section under the Design tab. To push your development changes to staging, simply click the downward-pointing arrow next to Development.

Escher will ask you to confirm the push operation. When you do, the entire set of changes is pushed to the staging branch as a single batch.

Alternatively, you can click on the branch name to view the list of changes prior to pushing them. You can even select individual changes to push on this page as well. Pushing from staging to production works the same way.

Rolling Back Changes

The occasional unintended push is inevitable. For that, we have the rollback operation. You can roll back an entire branch by clicking the upward-pointing arrow of the branch below the branch you want to roll back. For example, think of clicking on the production branch’s upward-pointing arrow as saying “Make the branch above me (staging) just like me.” You can also roll back individual changes to branches. Note however, that you cannot roll back changes to production. Changes to production are always immediate and final.

Branch Inheritance

You should think of the three branches as being stacked up, one atop the other, with Production at the bottom and Development at the top, like so:

Pushes always flow in the downward direction (e.g. “I pushed my changes down to staging.”) Rollbacks always flow up.

In addition, each branch inherits all the design assets of the branch below it. This allows Escher to record only the differences between each branch and the branch below it. As a result, Escher can maintain three distinct branches of your site without tripling the size of your site’s database.

For example, let’s say your production branch has a snippet named “header.” Your staging and development branches will access the production branch’s header snippet as needed until such time as you actually make a change to the header snippet in one of these branches. Only then will Escher copy the header snippet to your working branch (with your latest changes incorporated) or mark it deleted, as the case may be.

This implementation approach has a subtle but important side effect. Although each branch is completely independent of the branches above it (i.e. changes to any branch has no effect on the branches below it), the reverse is not necessarily true.

Going back to our header snippet example, if I apply a change to the production branch’s header snippet, that change will be reflected in the development branch unless I have previously saved a version of the header snippet to the development branch. This should have little practical impact, since if you follow the recommendation of not setting your working branch to “Production” you won’t be making changes directly to the production branch. So, why mention it? Well, you may find that at some point you need to push a small change directly to production.

“Hotfix” Deployment

Let’s say you have an urgent fix that needs to be deployed to your live site right away. But you’ve been working on other unrelated changes to the development branch that are not ready to be taken live. In this situation, your only choice would be to temporarily switch the working branch to production to make your change. Just be aware that you may need to re-apply that change to your staging and development branches as well.

Also be aware that switching the working branch to production creates a potentially dangerous situation, because the working branch is a global setting. If you are part of a team of developers, the entire team will be suddenly working on the production branch. So, good team communication is critical to ensure that nobody inadvertently affects the production branch (and live site) while you are applying your fix. Finally, don’t forget to switch the working branch back to development when you’re done!

Limitations

It is important to understand that Escher only branches the design elements of your site. Content elements and settings are not affected by branching. If you change a page or add a new page, that change will immediately be reflected in your live site (and in all branches). Similarly, if you change a site setting or preference, the change will take effect immediately and globally. Branching is a mechanism for easing maintenance and deployment of the site’s design – not its content or settings.

That said, Escher provides a very useful feature that provides the ability to preview new pages on the development and staging branches prior to publishing them. When you create a new page, just be sure to set its status to Draft. Draft pages are never displayed on a live (production mode) site. However, if you set the Development Draft As Published preference to Yes (under Expert Preferences), Escher will display draft pages when viewing your development branch.

There is also a Staging Draft As Published preference that accomplishes the same thing for your staging branch. Edit and preview your new page until you’re happy with it. Then simply update its status to “Published” to make it live on your production site.

Magic!

And there you have it. Escher provides a powerful yet incredibly simple to use implementation of branch management that allows you to develop and maintain your sites utilizing a best practice workflow, all without the headache of additional server and software maintenance. Out of the box. Like magic!