Setting up WordPress Projects with Subversion
By Traction
I’ve done a lot of projects using WordPress, and early on I realized the benefits of keeping my project files in a version control system like Subversion.
Tutorial by Traction Alumni, Gabriel Glider
For example, having a complete history of the changes I had made during my project. Then I started working on a WordPress project in a larger team, and found even more benefits of keeping the project in a Subversion repository. Having a single authoritative source for the project code, which all the team members check out from and commit changes to, makes it much easier to keep things in sync between individual developer environments and your staging and live servers.
It's a lot easier to manage a project with Subversion if you separate the parts of your project that need to be kept in the repository, and the parts that don't. For instance, generally you wouldn't want a file with your database connection info to be kept in the repository, because you should be using a different database on your local copy and your live server so that they can't cause problems for each other. However, separating versioned and non-versioned files can be tricky with WordPress. By default, WordPress installs all of its files at the root of your server, and your theme code and plugins live deep inside that file structure. That leaves you with a couple of equally bad choices. You could keep all the WordPress app files checked into your repository, but that makes updating to new versions of WordPress time-consuming and clunky. Or, you could have all the WordPress files ignored from the repository, but that makes it more difficult to set up a new dev or server environment.
Fortunately, there is a better way! Below, I'll explain the solution that worked well for our team on a recent WordPress project here at Traction. If you have any issues setting up the files I describe, you can check out my sample files here.
Setup
I'll assume that to start, you have an empty Subversion repository set up. First step is to check that out:
Replace the URL with your actual repository URL, of course. Now, I like to make a separate "htdocs" directory for the web server to use as the site root, so that if I have notes, maintenance scripts, etc., I can keep them in trunk and not worry about those getting served to the site's visitors.
Add WordPress
Now, we'll add WordPress as a Subversion external. That means that our repository just stores a reference to WordPress' own Subversion repository, and when you checkout your working copy, you get a copy of WordPress from their server.
When you run 'svn update' you should see Subversion checking out a bunch of files for WordPress into the "htdocs/wp" directory. As you might have guessed from the URL, you are pointing to a specific version (tag) of WordPress, which makes upgrading WordPress super simple. Once WordPress 3.2 is available, for instance, you would just run:
Configure WordPress
Now, there are a few more files to set up to get WordPress to work with this file structure.
Those commands create a copy of the default WordPress wp-content directory and configuration file in your htdocs directory. Also, we create a .htaccess file. This is what I use for the .htaccess file:
It's pretty much the same as WordPress' default mod_rewrite setup, except that it points to "wp/index.php" instead of the standard "index.php", since we have WordPress checked out in the "wp" subdirectory. Also, I redirect "wp-admin" to "wp/wp-admin" as a convenience.
Keep the Database Info Separate
Now, turning our attention to the configuration file, there are a few steps I would recommend. First, I make some changes to the section of MySQL settings—it's the first section, with 6 define() statements that define constants whose names start with "DB_". I remove those to a separate file that is not checked into the repository, so that different installations can share the same main setup in wp-config.php, but still use a unique database. So, cut that whole database section and paste it into a new file in htdocs called "db-config.sample.php". Save another copy in htdocs under the name "db-config.php", and put your actual database connection information in there.
Then, in wp-config.php, where the database stuff used to be, insert the following:
This loads in our database config file and tells WordPress where it's been installed relative to our site root. The last three lines make it possible to use the same installation on multiple domains, which is a common case when you have local development environments—you might set up your local install to be accessed at a fake domain like "project.local", or you might access it directly at your IP address, so it's good to tell WordPress to adjust its settings to match the domain name of whatever server it happens to be running on.
Finally, do be sure to follow the instructions in wp-config.php for generating authentication unique keys and salts. It's easy and it helps secure your site.
Check It In
Now we've got all the files set up, and we just need to configure how they're managed in the repository:
That sets it up so that the main configuration and sample database configuration are stored in the repository, but the local database configuration is ignored so you can have a custom one for each installation.
Good To Go
You're all set! Now, when a collaborator checks out her own working copy from the repository, all she needs to do is copy db-config.sample.php to db-config.php and enter her own local database settings. And whenever you commit a change to the version of WordPress defined in the externals setting, all the developers on your team will be updated to the new version the next time they run 'svn update'.
I hope these instructions prove useful—the techniques here have evolved over several projects and are still sort of a work in progress, so if you have any ideas, questions, or suggestions please leave a comment and let me know.
Earlier this week, I wrote an article on Mashable calling for brands to consider developing their own APIs. In it, I used Kraft as an example for how brands could do this.
There's more than one way to do things from a front end web development perspective. Tables vs divs? Layout and mouseovers in css or javascript? GIF and JPEG and PNG, oh my! Engineering is an art of tradeoffs.
You're sick of the holidays, aren't you? Awkward holiday parties. Long lines. Commercialism? That's ok. We understand. That's why there's Grouchmas, the holiday for those who've forgotten the meaning of merry.