This article assumes that you’ve read the basic svn howto and the more specific one provided on the WP Codex but would like to try or need a setup similar to that described here on a page called: Vendor branches. In short, you want to use Subversion to track/maintain local versions of both WordPress code and your own internal project code, side-by-side, all in the same svn repository.
Scenario:
Let’s say you have an in-house web developement project that is built upon or otherwise dependent on the WordPress core files. This can be for something as simple as creating/customizing your own WP themes and plugins, or as complex as maintaining your own modified versions of WP core files, with additional components/modules, etc. The important thing is that you imagine a scenario where you are already using Subversion to commit changes/updates to this internal project of yours. However, a problem occurs whenever a new version of WordPress is released. You need to upgrade the WP core files whithout losing any of the custom modifications you’ve been making up until now. Ideally, you would like to apply (to your internal project) only the changes made to the upgraded WP core files without over-writing any of your own work.
Solution:
“The solution to this problem is to use vendor branches. A vendor branch is a directory tree in your own version control system that contains information provided by a third-party entity, or vendor. Each version of the vendor’s data that you decide to absorb into your project is called a vendor drop.” (quote)
So, in this case, the third-party entity or vendor, is WordPress. What we want to do is: absorb the WP code into our own project. The rest of this article is going to illustrate the concept of “vendor drops” as they would apply to this particular scenario and using WordPress as the third-party vendor. Some of the benefits of this method are described in the article that the previously mentioned quote came from. In addition, this article goes on to describe the exact same process (but in more general terms) in a section entitled: General Vendor Branch Management Procedure. Well, here is my “Specific Vendor Branch Management Procedure” for WordPress.
Vendor Branch Management – Description
“Managing vendor branches generally works like this. You create a top-level directory (such as /vendor) to hold the vendor branches. Then you import the third party code into a subdirectory of that top-level directory. You then copy that subdirectory into your main development branch (for example, /trunk) at the appropriate location. You always make your local changes in the main development branch. With each new release of the code you are tracking you bring it into the vendor branch and merge the changes into /trunk, resolving whatever conflicts occur between your local changes and the upstream changes.” (quote)
Our Setup -
Let’s use WordPress 2.3.1 as an example. A newer version of WP (2.3.2) was just released and we’ll be using that version in a follow-up article to show how you can maintain this setup across multiple WP version upgrades without losing your local changes. However, for right now, we’ll assume that this is your first vendor drop and that your current project is already using Subversion and is also built against WP 2.3.1. In theory, you could use this same procedure with any version of WP – just make sure to start with an initial vendor drop that is the exact same version of WP as the one your project is currently using. Remember, we are not upgrading WP yet. We are just importing the WP code into our existing subversion-based system, side-by-side with our internal project. Note: Backup your files and database before attempting any of this. Also, although not strictly required, the following steps assume you have some kind of shell access (like ssh) and a command line subversion client (like svn).
Creating Vendor Branches -
1. Download Vendor Source Code
$ mkdir workspace
$ cd workspace
$ svn export http://svn.automattic.com/wordpress/tags/2.3.1/
…
2. Importing Initial Vendor Drop
$ cd 2.3.1
$ svn import . http://svn.yourdomain.com/vendor/wordpress/current \
-m "importing initial WordPress vendor drop"
$ cd ../
$ rm -rf 2.3.1
…
3. Tagging Initial Vendor Drop
$ svn copy http://svn.yourdomain.com/vendor/wordpress/current \
http://svn.yourdomain.com/vendor/wordpress/2.3.1 \
-m "tagging WordPress 2.3.1"
…
4. Copying Vendor Drop into a New Branch
$ svn copy http://svn.yourdomain.com/vendor/wordpress/2.3.1 \
http://svn.yourdomain.com/branches/newproject \
-m "bringing WordPress 2.3.1 into the new branch"
…
5. Check Out and Add Customizations
We check out our project’s new branch – which now includes a copy of our first WP vendor drop – and we begin customizing or re-applying any changes to the code. Unless you’re starting from scratch, this probably just involves copying over any files and folders that were previously a part of your internal project code. Since we made sure to import the exact same version of WP that was used in our in-house development (this is not an upgrade) – there should be no conflicts and fewer surprises.
$ mkdir newproject
$ cd newproject
$ svn co http://svn.yourdomain.com/branches/newproject .
$ cp -a /path/to/your/oldproject/* .
…
6. Resolve conflicts and Commit Changes
Type svn status to see what files were modified and resolve any conflicts. Run svn add and svn delete commands where appropriate. Commit the changes and our modified version of WP is now completely integrated into our in-house project.
$ svn ci -m "commiting changes into the new branch"
$ cd ../
$ rm -rf newproject
…
That’s It! You’re Done.
At this point you might be thinking to yourself: “Well, that’s not exactly a time saver.. now is it?” And, you’d be right! But we won’t stop there! With WordPress integrated into our in-house versioning system – we can now use svn merge to quickly perform WP upgrades on our internal project code without risk of ever deleting or over-writing our own work.
And, best of all, every change made to your internal project code – including those made to WP core files – will now be documented and tracked from within your own local version control system.
[ Be sure to check back for the follow-up article entitled: "Using Subversion with WordPress - Part 2: Maintaining Vendor Branches and Upgrading WP Core Files" ]