WordPress is managed by a centralized version control system called Subversion. Mirror of this repository are also available via Git, a distributed VCS.

The WordPress codebase can be accessed via numerous ways: using Subversion, using Git, through Trac (the bug tracker), and through a direct download:

How Code In WordPress Is Organized #

If you are using the “develop” repository, the core codebase is in the src directory. A downloaded package serves a “built” version of this directory, thus placing these files in the root. The codebase consists of around 1000 files and directories. Primarily:

Initial bootstrap files, such as index.php, wp-load.php, wp-blog-header.php, and wp-settings.php, appear in this src directory. Special handlers such as the XML-RPC, trackback, and comment submission endpoints, are also in the root.

The remaining files are divided into three distinct directories: wp-admin, wp-includes, and to some extent, wp-content.

wp-content #

The wp-content directory consists of user-defined and site-specific files, including themes, plugins, and uploads. The repository only contains a wp-content directory for the bundled plugins and themes.

Top ↑

wp-includes #

The wp-includes directory consists of the primary core and third-party libraries for WordPress. Many of these files are loaded as the application is bootstrapped.

The files in wp-includes go by a mostly standard set of prefixes and suffixes:

  • class-*.php – PHP classes. Some of these are external libraries.
  • ms-*.php – Code specific to WordPress multisite functionality.
  • default-*.php – Code that implements or defines default functionality, namely constants, widgets, and filters.
  • *deprecated.php – Functions which are deprecated.
  • *-template.php – Template functions for the relevant API.

The files in wp-admin/includes follow similar naming conventions.

Top ↑

wp-admin #

The wp-admin directory consists of the administration area for WordPress. The primary bootstrap is wp-admin/admin.php. Other special files include admin-header.php and admin-footer.php, the AJAX handler admin-ajax.php, and the generic POST handler admin-post.php. Most of the files in the wp-admin directory are pages in the WordPress admin.

The wp-admin/includes directory consists of the primary core and third-party libraries available and used in the administration area. Some of these are loaded as the admin is bootstrapped – see wp-admin/includes/admin.php for the primary list of files included.

Top ↑

JavaScript and CSS #

The wp-admin and wp-includes directories also have js and css directories, for scripts and styles. Third-party scripts are packaged in a compressed and minified state, which are available at http://wordpress.org/download/source/. Both minified and development versions are included for core scripts and styles, with the minified versions receiving the suffixes .min.js and .min.css.

The wp-includes directory has a number of third-party libraries in folders. The wp-includes/js directory, in particular, has jquery and tinymce directories, with the former holding jQuery, jQuery UI, and various plugins, and the latter holding TinyMCE and various TinyMCE core and WordPress extensions.

The wp-includes/script-loader.php file registers all bundled scripts and styles. Each script and style is given a date-specific version number (yyyymmdd), which is bumped by a committer when the stylesheet changes. The version number is added to the URL, forcing the browser cache to clear, and the new CSS or JavaScript to be loaded.

Top ↑

Searching and Browsing Code History #

To search the codebase, developers rely on either a project search tool in their code editor or IDE, or command-line utilities such as ack or grep. Browsing the codebase on Trac is manageable, but one particular feature is noteworthy: Trac includes an excellent user interface for the Subversion blame command.

To blame a line of code would be to determine who last edited that line, and when. To access this in Trac when browsing a file, click the Annotate link in the top right corner. Most consider the UI far more efficient than individual svn blame commands.

Core committers do not make changes to WordPress lightly, and commits should never occur without as complete understanding of the existing code as possible. If the code causes a bug, was that always the case? When was it introduced? Why? Is the code in question a fix for a different bug? These questions and more are very important. To learn more, read the section on Researching Code History With Subversion Annotate.

Top ↑

Installation #

When a WordPress install is initially run, if a wp-config.php file cannot be located, the wp-load.php file will suggest you visit wp-admin/setup-config.php to create the configuration file.

Once this is done, you’ll be taken to wp-admin/install.php. At this point, the database tables are created. The database schema is stored in wp-admin/includes/schema.php, and the installation libraries are primarily located in wp-admin/includes/upgrade.php.

Top ↑

Database Upgrades #

The upgrade.php also includes database upgrade instructions. Whenever something about the database needs to change with a new version of WordPress – whether that means altering the database structure, or updating some database content – an upgrade routine can be triggered. Indeed, you can safely update from WordPress 0.70 to the latest version with the database keeping up with the changes over the better part of a decade of progress.

Knowing when to upgrade is handled by a number in wp-includes/version.php, the WordPress database version. This number corresponds to a revision number of the codebase, generally the revision that last introduced a database upgrade routine. When the number in the code differs from the number stored in the database, the routines in wp-admin/includes/upgrade.php are run.

The function wp_upgrade() calls, among other functions, upgrade_all(), which will run the appropriate routines in sequence. In order to trigger a new routine, a “schema bump” – changing the right numbers, including the WordPress database version in version.php – needs to occur.

Changes to the database structure are handled by a function called dbDelta(), which takes the table definitions, compares them to the existing schema, and makes any changes – adding new tables, altering fields, adding indexes – that are required. For dbDelta() to run over the core table definitions, the DB version in version.php simply needs to be bumped.

Top ↑

File Updates #

Core developers generally distinguish between database “upgrades” and version “updates.” Updating WordPress to the newest codebase (via the user interface) triggers a complex series of actions.

Prior to any update, WordPress has already polled api.wordpress.org to determine whether it needs to update, and if so, where to find the new version. Once the update is triggered, WordPress will download the ZIP archive and unzip it to a temporary directory in wp-content/upgrade. A single file, wp-admin/includes/update-core.php, will be copied out of the temporary directory and over the existing wp-admin/includes/update-core.php, at which point it will be executed. Thus, newly downloaded code then handles the main process of copying over the new files. This allows us to provide instructions specific to the new version, such as which files are old and can be removed.

Top ↑

Exploring The Code #

These tools may be useful in exploring the WordPress codebase: