On WordPress.com VIP, we use Subversion to version all of your theme and plugin code. As you may know, one of the primary benefits of using a version control tool like svn is the availability of a complete history of your code, from your very first commit to the latest. Here are some quick tips that should help you access this history and, when necessary, quickly roll back your deployed theme to a previous state:
The Time Machine
Every time you commit a change to your theme, Subversion remembers by creating a version. Each of these versions is assigned a unique number and certain other meta, namely: the username of the person who made the version, the date and time of the version, the number of lines of code changed in the version relative to the previous one and a commit message indicating the nature of the changes in the version. You can inspect your theme’s version history on the command line using the svn log command (documentation: cli, tortoiseSVN.) Here is some sample svn log output for Automattic’s test theme on VIP:
vip/test-theme$ svn log .
------------------------------------------------------------------------
r69251 | viper007bond | 2012-06-20 21:09:52 +0000 (Wed, 20 Jun 2012) | 1 line
Remove testing code
------------------------------------------------------------------------
r69209 | batmoo | 2012-06-20 13:59:49 +0000 (Wed, 20 Jun 2012) | 2 lines
auto-deploy: rm image in a subfolder
------------------------------------------------------------------------
r69197 | batmoo | 2012-06-20 13:40:55 +0000 (Wed, 20 Jun 2012) | 2 lines
Auto-deploy: testing a php + css commit
------------------------------------------------------------------------
r66930 | tottdev | 2012-05-27 11:19:52 +0000 (Sun, 27 May 2012) | 1 line
reverting error code
Now that you can see a list of your previous versions, you may want to inspect one in more detail. What changes did a previous commit introduce? To help you find out, svn provides the svn diff command (docs: cli, tortoiseSVN.) This utility is quite flexible, but for the present purposes, a fairly typical case would be:
vip/test-theme$ svn diff -c 17546 .
Index: header.php
===================================================================
--- header.php (revision 17545)
+++ header.php (revision 17546)
@@ -6,7 +6,6 @@
-<meta name="generator" content="WordPress "/>
<link rel="stylesheet" href="?2" type="text/css" media="screen" />
The -c flag shows a change set resulting from a single revision, but there are many other options including -r n:m (show differences between revision n and m) and more — see the svn diff documentation for full details.
Revert! Revert!
Sometimes you many need to roll back code once you’ve committed it to WordPress.com VIP’s theme repository. This might happen for a number of reasons, including the removal of temporary code, a change in business needs, or a performance problem or error. WordPress.com VIP engineers are here to help you in any of these situations, and it’s possible for us to roll back your code for you in an emergency. However, the quickest roll-backs happen when you revert and commit the code yourself. Here’s how to prepare and push a roll-back:
1. Update your theme’s working copy to the latest revision (use
svn up your-theme
or tortoiseSVN.)
2. Use svn log to find out how far you’d like to roll back. Suppose your log reveals something like:
r4 -- change paint color
r3 -- introduce clunk engine
r2 -- modify blee tag
r1 -- add snorkle
In retrospect, you realize that something went wrong sometime after r3. You therefore decide to roll back r3 and r4.
3. Use svn merge to roll back the code. A typical cli command for this would be:
vip/my-theme$ svn merge -c -4 -c -3 .
This “un-does” the commits with version numbers 3 and 4, and rolls the code back to its previous state as of revision 2. As with svn diff, the merge command admits lots of different syntax combinations. You can read about some of those here and here. You can also roll back easily using clients like tortoiseSVN.
4. The merge you just performed has produced a changeset in your working copy. Commit your roll-back like any other change using svn commit. Make sure that you include an explanatory commit message such as “roll-back of r3 and r4 due to JS error”. Your message should indicate which versions are being rolled back, and for what reason. This will help WordPress.com VIP deploy engineers quickly deploy your changeset. Pure roll-backs usually require little or no review, and can be deployed almost immediately, so make sure your change only contains the roll-back, and nothing else. In an emergency situation, you can open an urgent ticket requesting a deploy of your roll-back. Generally this is not necessary, however, and we request that you reserve urgent tickets for when your site is down or for other serious end-user issues.
Notes:
1. We encourage you to think in terms of “rolling back” code instead of reverting individual commits. It is possible to revert things out of sequence. For instance in the previous example we could have reverted r3 but not r4. However, to do so ignores the possibility that something in r4 may depend on something in r3. In almost all cases, it’s safer to roll back all commits in sequence, especially if doing so quickly.
2. Data dependencies. Before a major roll-back it’s good to take a second to consider whether the underlying data has changed in a way that would cause problems with the old code. Have the content or options been modified in any way, including by CLI scripts? This is not usually an issue, but can be in certain cases.
3. Confusingly, subversion also features a command called svn revert whose purpose is not to take your code to a previous state, but only to un-do local un-committed modifications. Therefore we use the term “revert” both in the sense of “roll-back” and the sense of svn revert.
4. Finally, There are an extremely large number of Subversion clients which make all of this very easy. Cornerstone is a a great (though somewhat expensive) client for OSX.
WordPress VIP Lobby 