File Organization

Even though MultilingualPress is available on WordPress.org and its SVN server, we use GitHub (i.e., Git) for development and version control. While the WordPress.org SVN repository and the generated ZIP file only contain what the end-user really needs for using MultilingualPress, the GitHub repository also includes additional development files (e.g., resources, and tests). In this article, I would like to present and discuss the file organization of MultilingualPress’s development repository.

File Organization

File organization in the development repository.

The Development Repository

In the GitHub repository root, you can find individual folders for assets, resources, sources, and tests. And then there is a bunch of files, for instance, several config and markdown files, and a multilingual-press.php file. None of them is required to use the plugin—yes, not even the PHP file.

So, let’s have a closer look at the folders and files. For the sake of a better understanding, however, we don’t do this in alphabetic order, but in a somewhat logical order.

Sources

The src folder contains what is required to use MultilingualPress, and thus will be shipped to and by WordPress.org. In this folder, we currently find assets (images, scripts, and styles), language files (which soon will be removed in favor of the official WordPress.org GlotPress project for MultilingualPress), the license and readme files, and the actual PHP source files.

Assets

The assets folder in the root (not to be confused with src/assets) contains the assets for the WordPress.org SVN repository (i.e., banner and icon images, and screenshots). These files are not required for using the plugin, but only for the official plugin page in the WordPress.org plugin repository.

Resources

For both the back end and the front end, there is only a single CSS file (in a minified version, and in an unminified, debugging-friendly version). The CSS development, however, does not happen by using a single large unminified file, and then compressing it. Instead, the basis for the plugin styles consists of several .scss files that are structured in the resources/scss folder. We use a few reusable modules, and split individual styles into partial files according to their individual context (in terms of plugin features or modules).

Similar to styles, the shipped plugin scripts are just a single file for each back end and front end (again, in minified and unminified versions). The development of the script files happens on the basis of a base file (e.g., resources/js/admin.js) and several other independent files in a folder named after the base file (i.e., resources/js/admin for resources/js/admin.js).

Both the WordPress.org assets as well as the plugin images are all shipped in a compressed and web-optimized version. The high-resolution/high-quality originals live in the resources/assets and resources/images folder, respectively.

Tests

Unsurprisingly, the tests folder contains tests. Currently, there are PHPUnit tests for PHP files only, but once we are done with refactoring all JavaScript files there will be QUnit tests, too. The tests are separated into folders named after the individual testing tool (e.g., phpunit for the PHPUnit unit testing framework), and then further structured according to the different test levels. So, QUnit unit tests for JavaScript live in tests/qunit/unit, while tests/phpunit/integration contains PHP integration tests using PHPUnit.

The Proxy File

To make working with the development repository as easy as possible, there is a proxy (main plugin) file living in the root. It is named exactly like the (real) main plugin file located in the src folder, and it pretty much only calls (i.e., requires) the real thing. By doing this, you can just clone the GitHub repository into a project’s plugin directory and simply use the plugin as if installed from WordPress.org—no need to copy the contents of the src folder to a new multilingual-press folder, or anything like that.

The Advantages

There are several advantages of organizing a plugin like this. Here are the most obvious ones:

Separation

Apart from possible config files, which are located in the root, you always know where to look when you search something. If you want tests, look inside the tests folder. If you don’t want tests at all, you only have to remove the tests folder. When working on styles and/or JavaScript of some (maybe new) module, you don’t have to fight your way through a huge file, but can use a small file dedicated to the very module. You always have the original resource files for anything you ship in a modified version (e.g., images).

Assets

We can have an assets folder in the root that contains the WordPress.org assets, while the actual plugin assets are located in src/assets. No name conflict, no need to make up a name for what actually should be assets anyway.

Release

Publishing a new release on WordPress.org is as simple as this:

  • clone the repository (GitHub);
  • remove everything from trunk (SVN);
  • copy the contents of the src folder to trunk
  • add a new tag folder (SVN), in case you use tags (which you should);
  • add all new files to SVN;
  • commit.

Easy, right?

The Disadvantages

So far, we’re unaware of disadvantages. Are there any?