Pages

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 3.4.0 or 3.5.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 3.4 and 3.5 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. 3.5.2, in the case of the 3.5 branch. These should generally be considered stable, but care should be taken when a minor release is being prepared.

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.

Patches are created using a working copy of WordPress trunk that has been checked out of the repository. Subversion keeps a history of the code, but it also provides centralized repository so that 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 they generate a patch that shows their changes, since they cannot modify the central repository. 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 (e.g. during the preparation of 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 Your Patch Committed]

Top ↑

Finding an SVN Client #

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

For Windows, the recommended SVN client is TortiseSVN, which is free and open source.

For Mac, the recommended SVN client is Cornerstone, which must be purchased.

Top ↑

Learn More #

If you would like to learn more about working with Subversion, check out Installing A Version Control System, Installing WordPress Via SVN, and Working With Patches in the Tutorials and Guides section of this handbook.