WordPress.com VIP platform specific
This document is for sites running on WordPress.com VIP.
- What is a code review?
- How long does a new theme or plugin code review take?
- What do you look for during Code Review?
- Theme Review
- Plugin Review
- Deploy Review
- How to commit code
What is a code review? #
Every line of code that is committed to WordPress.com VIP is reviewed by the VIP Team. We don’t do in-depth code reviews to add more time to or delay your launch schedules. We do these lengthy code reviews to help you launch successfully.
The goal of our reviews is to make sure that on your launch, your site will be:
- Secure, because pushing a site live with insecure code presents a liability to you and your whole userbase;
- Performant, because going live and finding out that your code can’t handle the traffic levels that your site expects puts most of your launch efforts to waste.
We also review for development best practices to make sure that your site will continue to live on without significant maintenance costs or major issues when WordPress is upgraded.
There are typically three ways you will submit code to us:
- Theme Review: You are launching or redesigning your site, which means you will submit a complete theme to us (with plugins included).
- Plugin Review: Your site has already launched and you are looking to include a plugin that is not already a feature on WordPress.com or in our shared VIP Plugins directory. The plugin must be reviewed before being included on your site.
- Deploy Review: This is for more experienced VIP Developers who have been granted write access to their production SVN repo and are looking to make changes to the site. Every commit is reviewed before it can be deployed.
How long does a new theme or plugin code review take? #
Please budget three weeks for the initial review process: one week for our review, one week for your fixes and one week for us to validate fixes and move your code into production SVN. Note however, that this is three weeks from when the review starts, not necessarily from when you submit. We schedule reviews bi-weekly and will let you know your review start date once it’s on the schedule. Review slots are generally scheduled at least a week in advance, so you will want to let us know as early as possible that you plan to submit code for review. The more information, the better. When do you plan to submit the theme or plugin? How many lines of code do you estimate submitting? When do you aim to have this code in production?
Include us in your plans as early as possible. It will make the initial theme or plugin review move faster and more smoothly.
What do you look for during Code Review? #
Here’s a guide to what the VIP Engineering Team looks for when reviewing your code. We strongly recommend looking at this document before submitting your code to expedite your review process.
Theme Review #
Overview: You are submitting a theme to be included on WordPress.com VIP. In this process, your theme and plugins will be reviewed line by line, making sure your code is secure, optimized, and well-architected. It typically takes 10-15 business days for a full theme review, but this can vary depending on complexity of code and the size of review queue.
Getting a Theme Ready for WordPress.com VIP #
- Development Environment: Make sure your local development environment is set up correctly, as described here.
- Code Review Guidelines: Make sure to read all the code review documentation. The what we look for page is a great start.
- Starting Out: If you’re looking for a barebones theme, to start from, check out _s, which is built and maintained by Automattic.
If you’re looking for something more robust to work from, we recommend selecting from one of the 300+ pre-approved WordPress.com themes. The code for all the free themes are available here.
If you’re interested in working with a Premium theme, let us know and we can provide access to the code.
- Sharing is Caring: To streamline your review, be sure to use WordPress.com functionality (available in Jetpack), our Shared VIP Plugins, our Helper Functions, and our Shared Libraries whenever possible.
- WordPress Standards: We recommend all developers follow WordPress Coding Standards. It ensures consistency, code cleanliness, and speeds up a review.
- Communicate Early: We recommend getting in touch with us early to communicate your planned launch date, but also to chat with us about how you plan on architecting your site. The earlier you include us in the process, the more streamlined your review will be. Please take a look at our recommended Launch Checklist.
Theme Review Checklist #
A theme must meet all the following requirements before being approved:
- You’ve reviewed your code for common blockers.
- Your theme/plugins are either licensed under the GNU Public License v2 (GPL2), a compatible license, or are completely custom code that you’ve written in-house—split or proprietary licenses are not allowed. The reasoning for this is that you, and we, need to have the legal rights to modify the code if something is broken, insecure, needs optimization, etc.
- Your code has been QA’ed in an up-to-date local environment.
- Your code has been run through the PHPCS, all blocker-level issues are addressed, and non-blocking errors detailed in your submission materials.
- The VIP environment is initialized with our helper function.
- All data is properly validated, sanitized, and escaped. The first two apply to whenever you’re handling user-submitted data (e.g. post meta boxes, frontend forms, etc.) and the latter applies to whenever you’re printing data from the database.
- Scripts and styles are enqueued, and are done so on the proper hook.
- The theme does not use
- All custom functions are prefixed.
vip_powered_wpcom()function is called in the theme’s footer.php.
- The theme follows WordPress Coding Standards.
Ensuring a successful theme review #
- If the theme is more than just a basic theme, it will speed up the review process for us to fully understand the purpose of any custom code and what it’s trying to accomplish. Therefore, the more technical and in-depth documentation you have at the time of theme submission, the better.
- VIP does not accept off-the-shelf, commercial themes since they tend to be overloaded with excess functionality and code which are potential security and performance risks. If you have an off-the-shelf theme that is lean, mean, secure, and performs well then let’s talk. If you’re looking for something robust to work from, we recommend selecting from one of the 300+ pre-approved WordPress.com themes. The code for all the free themes are available here.
- If you’re running a number of sites you’ll want to take the common theme approach – it’s a single theme used across multiple sites. If each site contains some unique functionality you can add that via Child Themes. Learn more about child themes here.
- Please make sure that the code you submit for review is well-tested and includes all the information needed to function on a clean, current WordPress installation. If any content needs to be setup in order to test your theme, please provide a WordPress export with sample data.
- We review all plugins you include in your theme. We have reviewed a small, but growing list of plugins, and modified some of them to make them more stable, secure, and performant. If your site hasn’t launched yet on WordPress.com, then please only consider the few plugins crucial for your user experience. It will make the launch process go much smoother.
- Please note that plugins and other functions that alter the database structure or perform write operations on the filesystem interfere with our architecture, and we likely will not be able to approve these kinds of scripts. More details are shared in Best Practices.
- Make sure that all of your plugins are included and running from within your theme folder. The plugins will be loaded by the themes’ functions.php file or similar methods. Some plugins need alteration of paths and/or urls in order to keep functioning in such an environment.
How to submit a theme #
Congrats! You are ready to submit a theme for review. To do so, zip up your theme and submit it to us via the VIP Support Portal. Here’s an example zip command that excludes development environment files that wouldn’t be included on WordPress.com:
zip -r <theme-dir>.zip <theme-dir> -x "<theme-dir>/.git*" "<theme-dir>/node_modules*" "<theme-dir>/bin*" "<theme-dir>/tests*" "<theme-dir>/phpunit*" "<theme-dir>/vendor*" "<theme-dir>/.sass-cache*" "*.DS_Store"
Please include the following information in addition to attaching the results from PHPCS (required):
- What date are you targeting to have this code launched? Please allow sufficient time in your schedule for our review and launch process.
- Please provide a 1-2 sentence description of your submission.
- Please provide a brief architectural overview of your code.
- Is the code GPL compatible? WordPress code is licensed under the GNU Public License v2 (GPL2). All theme and plugin code needs to be GPL compatible. Custom code you’ve written in-house—split or proprietary licenses are not allowed. The reasoning for this is that you, and we, need to have the legal rights to modify the code if something is broken, insecure, needs optimization, etc.
- Is this code based off of existing code? If yes, provide specific details (eg: “includes code from XYZ project…”)
- Does this code run successfully in a local development environment?
- Has this code been run through the PHPCS, and have all blocker-level issues been addressed and other errors closely investigated? You’ll need to upload PHPCS results along with your submission.
- Does the code correctly escape, sanitize and validate data? Our requirements may be more stringent than you’re accustomed to. Please follow our “late-escaping” best practice.
- Which URL do you intend to use for this site? (We do not support the www subdomain, or mapping domains to a subdirectory)
- Is the theme named correctly?
- Does this theme follow the WordPress coding standards?
- All custom functions must be consistently prefixed. Which prefix did you use?
- Does the themes root directory include the
vip-init.phpincluded at/near the top of
- Are scripts and styles are enqueued, and done so on the proper hook?
- Is the
vip_powered_wpcom()function called in the theme’s
- Does the
404.phpcontain any database queries?
- Is there a “plugins” sub-directory at the theme root?
- Which plugins does this theme use?
- Are plugins in the “plugins” sub-directory called properly in
functions.php? The plugin should not rely on the plugin activation and deactivation hooks as VIP plugins are a part of your theme and are loaded using
require_once()rather than the plugins menu.
- Are there any external services, dependencies, or applications that utilize or rely on this VIP site or content (e.g. a mobile app that fetches content from the site)? If yes, how do these services interact with the site? (eg: RSS, XML-RPC, etc.)
- Are there any significant features or components that are to-be-developed before launch, but not included in this initial submission?
- Who are the main representatives from your team responsible for launch and should be included in communications?
What happens now? #
The VIP Team will now peer review your theme to prepare it for production on WordPress.com VIP.
Our code review process is collaborative, and we hope to not only make your theme better, but also help you become a better WordPress developer. For reviews, we use the VIP Review Trac to help give you feedback on any errors, irregular code, or calls in the theme that must be fixed before the theme can be approved. Learn more about the review process with Trac here.
After your theme has been approved, we’ll provide access to your theme’s subversion repository.
Plugin Review #
Overview: If you are interested in using a plugin that isn’t available as a pre-approved VIP shared plugin, review it for stability, performance, and security before it can be used on WordPress.com.
Plugin Review Checklist #
A plugin must meet all the following requirements before being approved:
- WordPress code is licensed under the GNU Public License v2 (GPL2). All plugin code needs to be GPL compatible or custom code you’ve written in-house. Split or proprietary licenses are not allowed. The reasoning for this is that you, and we, need to be have the legal right to modify the code if something is broken, etc.
- The plugin needs to run on the latest version of WordPress with MultiSite enabled.
- The plugin should not directly write to the filesystem as this will not work with our distributed environment. You can use the WordPress API though, such as
- The plugin should use the existing database tables and structure (no alterations). Custom post types, custom taxonomies, post meta, etc. are incredibly flexible.
- The plugin should not rely on the plugin activation and deactivation hooks as VIP plugins are a part of your theme and are loaded using
require_once()rather than the plugins menu.
- The plugin must follow WordPress Coding Standards.
- The plugin must follow all VIP Code review guidelines
Other helpful information #
- If you are submitting a third-party plugin for review, we still require your team to complete an internal code review following our stated guidelines before submission.
- If you’re currently using Jetpack on your self-hosted WordPress site, you don’t need to include it on your WordPress.com VIP site—every feature that exists in Jetpack is already included in WordPress.com.
- When submitting a plugin, we appreciate as much detail as possible about how the plugin will be used and what it’s trying to accomplish (examples are particularly helpful). Our code review process is collaborative — we encourage you to introduce yourself to how it works.
How to submit a plugin #
Congrats! You are ready to submit a plugin for review. To do so, zip up the plugin and submit it to us via the VIP Support Portal. Please include the following information:
- Name of Plugin:
- Expected launch date:
- Short description of plugin:
- Brief architectural overview:
- Is the code GPL compatible, or custom-code written in-house?
- Does the code follow WordPress Coding Standards?
- Does the code properly escape, sanitize and validate data?
- Have you checked the plugin for “Blockers” as listed in our documentation?
What happens now? #
The VIP Team will now peer review your plugin to prepare it for production on WordPress.com VIP.
Our code review process is collaborative. For reviews, we use the VIP Review Trac to help give you feedback on any errors or irregular code that must be fixed before the theme can be approved. Learn more about the review process with Trac here.
Once your plugin is approved
Plugins on WordPress.com VIP are organized differently than a standard self-hosted WordPress.org site, since on VIP you only have access to your site’s theme folder. To use plugins on a WordPress.com VIP site, you add them to a “plugins” directory within your theme directory, and require_once/include_once them in
require_once( __DIR__ . '/plugins/custom-plugin/custom-plugin.php' );
Deploy Review #
Once your theme and plugins have passed review, they are moved to the VIP production repo. Eventually, you will be granted the necessary access to submit code changes. Every commit is reviewed to ensure that it is secure, optimized and performant before it can be deployed. We also run automated PHPCS checks against all changesets so it’s worth setting up PHPCS in your local dev environment.
At VIP, we believe in a partnership with our clients. Deploy review is the most hands-on way we work together to ensure that your site is performant and secure. Feedback will typically be shared with you in a ticket, and if you ever have questions or concerns, we are always happy to discuss. We typically have three types of feedback we share:
Blockers: This category includes all security issues as well as any serious performance concerns. Code that fits in this category will not be deployed, and will be reverted if the concerns are not addressed by the end of the business day.
Fixes Required: This category includes potentially non performant code, along with code that does not follow best practices. If you have received feedback and your code has been deployed it means that the feedback needs to be addressed as soon as possible, typically within one business day.
Informational feedback: This category contains suggestions from our team. During code review we will sometimes spot bugs or have suggestions for clarity, architecture, or readability. We will always explicitly note which changes are not required but are informational in nature.
Tip for deploying on VIP:
- Only commit tested code. Never use WordPress.com for testing or debugging. If there is something you cannot reproduce or work out in your local environment, please open a ticket and ask for assistance.
- Including a detailed commit message speeds up the time it takes us to review and deploy the code, and is also essential for future debugging or in case of emergencies.
- If you have significantly large or complex changes (anything over 1,000 lines) to push, please send the changes in as a patch ahead of time.
- As always, follow Best Practices and Code Review Guidelines.
Keeping the queue clear #
Given commits in subversion are linear, any commit that has feedback may delay the deployment of earlier, or subsequent, commits. Keeping the queue clear is important so that if any emergency commits need to be made, those can be deployed quickly.
For this reason, if commits have been sitting in the queue for a while, without feedback being addressed we may revert them to keep the queue clear. We’ll generally allow 24 hours but in some instances, such as weekends, we may revert sooner. If you need help generating a diff to re-commit the changes, let us know.
How to commit code #
Please see Accessing Your Code for more information.
Once you’ve committed your code #
We review everything before deploying, so you can expect tickets, commits, or reverts from us if we find any issues.
If issues are found in submitted code and it’s a simple fix, we fix the issue and notify the developer before pushing the code live. If it’s a more complex problem, we do not deploy the code. We may revert the code or hold the deploy depending on the severity of the issue(s) and notify the developer with guidelines on how to fix the problem.
We deploy code changes to VIP sites throughout the European and North American business day and strive to have all changes live within two hours. Note that changes to CSS files and images are deployed automatically.