Pages

Contents

What is SVN? #

WordPress uses Subversion (SVN), a very popular version control system managed by the Apache project, to manage changes to its codebase. A change to the WordPress codebase increments the revision number. Individual changes are called commits or changesets. These are denoted as either r12345 or [12345].

The WordPress repository of code is organized into three main directories: tags, branches, and trunk.

  • The trunk directory contains the latest development code in preparation for the next major release cycle. The latest revision may be unstable or broken at times. The latest development code may be referred to as trunk.
  • The tags directory contains individual snapshots of each official release, such as the 2.8.0 or 2.9.1 tags. Once created, these are unmodified, and these are used to build the download packages.
  • The branches directory contains directories that consist of the latest code for each major release, such as the 2.8 and 2.9 branches. Minor release development occurs within the branch. For example, a critical bug that affects the latest release may be fixed in both trunk and the most recent branch, in preparation for a point release — i.e. 2.9.1, in the case of the 2.9 branch. These should generally be considered stable, but care should be taken when a minor release is being prepared. [todo] point release philosophy [/todo]

While it takes a developer with commit access (called a committer) to change the WordPress codebase, anyone can suggest a change in the form of a patch. A patch is a special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff (after the Unix command to generate a differences file). Patches have the extension of either .patch or .diff.

To create a patch, you will first need to check out a working copy of WordPress trunk. Subversion keeps a history of the code, but it also provides centralized repository that way committers do not overwrite each others’ changes. (A conflict occurs when a patch changes code that has since been modified.) For this system to work, each committer keeps a working copy of the same repository. Code is checked out as a local working copy, and then checked in (committed) to the centralized repository.

Contributors follow the same process, but as they cannot modify the central repository, they generate a patch that shows their changes. This patch can then be applied to the individual working copies of other contributors or committers, so it may be reviewed, tested, and potentially committed.

When writing a patch, it is important to always update to the latest version of trunk. Patches should never be written against a released version such as a tag or branch, with very rare exceptions. [Link: point releases.] Trunk is, however, a moving target, which can cause patches to become stale and require a refresh — they no longer apply properly, because code in the central repository no longer matches what the patch is attempting to change. Patches that alter a significant number of lines or files should generally be brought to the attention of committers sooner rather than later. [Link: getting attention]

Top ↑

Finding an SVN Client #

Many developers run SVN commands using the command line interface such as Terminal on the Mac. Even most basic commands are simple, the command line is reasonably intimidating for many users. Many developers do rely on UI applications though, either for regular use or to handle complex actions more effectively.

On Windows, the premiere client is TortiseSVN, which is freeware. Lead developer Peter Westwood wrote a tutorial many years ago. [todo] link [/todo]

On Mac, you may wish to purchase Versions or Cornerstone [todo] (mac freeware?) [/todo]. Lead developer Mark Jaquith wrote a tutorial on command line usage. link

Top ↑

Advanced Topics #

Using the Command Line #

Checking out SVN trunk #

If you do not yet have a directory set up to do WordPress core development in, you could create it with ‘mkdir’:

mkdir ~/WordPress-dev

Go to the directory where you will be hacking the WordPress core: 

cd ~/WordPress-dev

‘Checkout’ the WordPress core trunk with SVN, then enter the ‘trunk’ directory, which contains the WordPress code:

svn checkout http://core.svn.wordpress.org/trunk

cd trunk

Happy hacking!

Top ↑

Creating a Patch #

Once you’ve edited files and made changes, you will want to generate a patch which records the differences between your version of the files and those from trunk. To do so, ensure that you are in the ‘trunk’ directory created by your SVN checkout, then run the following, where ’00000′ is replaced with the ticket number from trac:

svn diff > 00000.patch

If you’ve made multiple changes to trunk and you wish only to submit a patch for certain select files or directory trees, these can be passed to ‘svn diff’ as arguments. In the following example, only changes made in the ‘wp-includes’ directory tree and the ‘theme-options.php’ file in the twentytwelve theme will be recorded. This means that if you were tinkering with some of the JavaScript or CSS files in the twentytwelve theme, but those changes are incomplete or not relevant to this trac ticket, they will not be included in the patch:

svn diff wp-includes wp-content/themes/twentytwelve/inc/theme-options.php > 00000.patch

Top ↑

Applying a Patch #

So you have your SVN ‘trunk’ and you want to test out a patch that someone submitted in trac. Ensure that you are in the ‘trunk’ directory, then download the patch into that directory, if you have not done so already:

curl -O https://core.trac.wordpress.org/raw-attachment/ticket/00000/00000.patch

Note: If you download the patch this way, be sure that it is coming from the ‘raw-attachment’ directory on the trac server. You can grab this URL for copy-paste by clicking on the patch in trac, then grabbing the URL linked to by ‘Original Format’ at the bottom of the page.

From the ‘trunk’ directory, where you have downloaded the patch file, you can apply the patch against the source tree by issuing the following command:

patch -p0 < 00000.patch

Now, the ‘trunk’ source tree on your computer has been patched with the file you downloaded, giving you the version of the source tree that the developer who submitted that patch was working with.

Top ↑

Bash Help #

Here’s a few useful tips if you are new to BASH and the *nix commandline:

Top ↑

Location #

pwd – Print Working Directory
Show the current directory that you are working from.
cd PATH – Change Directory
Change the current directory to PATH, which can be an absolute or relative path or directory name.
ls – List Directory Contents
List the contents of the current directory. If you wish to list another directory without changing to that directory, use ls PATH.

Top ↑

File Redirection #

PROGRAM > FILENAME – Redirect Output to File
Instead of displaying the output of the program, put that output into the FILENAME file. This will create that file if it does not exist, or overwrite it (destroying anything which was in that file previously) if it already exists.
PROGRAM < FILENAME – Redirect Input from File
Instead of using your keyboard for the input of the program, use the contents of the FILENAME file as the program’s input.

Top ↑

More Help with Bash #

man PROGRAM – Open the System Manual for PROGRAM
To learn more about a program and all of its command line options (arguments), browse through that program’s manual pages with the ‘man’ command.
Check out one of the many books devoted to learning to interact with the command line
For instance, this free one:

Introduction to the Command Line

Helpers:

http://nacin.com/2010/05/13/my-wordpress-bash-functions/

http://blog.ftwr.co.uk/archives/2008/07/19/my-wordpress-toolbox/