Setting up your Development Environment

Like all software development, you should develop and test your code in your local development environment before committing the code to WordPress.com VIP. This document will help you set up an environment to aid development of your WordPress.com VIP hosted site.

Please note: This document relates to the WordPress.com VIP platform. VIP Go related documentation can be found here.

Caveats

WordPress.com is a large web application that has been developed over the past 10+ years. Please note that the environment setup described here will not provide a 1:1 copy of your production environment. While we’ve tried to bridge various gaps, many features are very challenging to reproduce locally and environmental differences will exist. A non-exhaustive list of these differences can be found here.

We’re also happy to help guide and assist you with any concerns/issues you have with these differences.

Getting Started

  1. Install a local Multisite WordPress environment. We recommend Chassis or VVV.
    • Use Chassis if you want an environment that’s simple yet powerful. It’s a minimalist development setup that boots up fast and gets out of the way.
    • Use VVV if you want an environment that comes with lots of features, is highly extensible, and can run many different site configurations.
    • You can also roll your own setup (like something built on Docker).

    Note: Your environment should be be set up as a Multisite (Chassis has a config flag; VVV requires a custom site template; and custom setups can follow the Codex).

  2. Install VIP Plugins and Helpers to wp-content/themes/vip/plugins:
    svn co https://vip-svn.wordpress.com/plugins/ wp-content/themes/vip/plugins
    

    You should svn up daily to ensure you’re working with the latest code.

  3. Install VIP mu-plugins to wp-content/mu-plugins:
    git clone --recursive https://github.com/automattic/vip-wpcom-mu-plugins wp-content/mu-plugins
    

    You should git pull daily as well to ensure you’re working with the latest code.

    The readme covers other environment-specific things like concatenation and caching that you may want to set up as well.

  4. Install your theme to wp-content/themes/vip/{your-theme}. If you’re just starting out with VIP, please read through Anatomy of a VIP Theme to get an overview of what your theme should look like.

wp-content

When set up correctly, your wp-content directory should likely look something like:

wp-content/
    plugins/
    mu-plugins/
        0-local.php
        ...
    themes/
        vip/
            your-theme/
                plugins/
                    your-custom-plugin/
                        your-custom-plugin.php
                        ...
                functions.php
                style.css
                ...
            plugins/
                vip-init.php
                ...    

The Stack

As of March 13, 2017, we are using the following pieces of software across our stack:

  • Debian Wheezy
  • PHP 7.0
  • MariaDB 10.1
  • NGINX
  • Memcached

Note that the one most likely to impact your day-to-day work is the PHP version.

WordPress Updates

We are usually running the latest stable release of WordPress core on WordPress.com.

We try to provide adequate notice for releases of major versions on the platform. When a pending release is announced, we recommend switching over your local environment to use the beta tester plugin or a SVN checkout of trunk to make sure you’re running the latest version and can test for any issues before they are rolled out.

Content

You can use the built-in export/import functionality in WordPress to populate your local environment with test data. You can generate an export from your site’s Dashboard and then use either wp-cli or the Dashboard Importer to import the content. If you have issues exporting or importing, please get in touch and we’d be happy to help.

If you are just starting out and need some data to play with, check out the demo files that the Automattic Theme Team uses for building and testing new themes.

You can also use WP Options Importer to export/import options (like widgets, plugin settings, etc.).

Debugging

You should always have debugging enabled in your local environment help catch errors as you develop:

// In your wp-config.php
define( 'WP_DEBUG', true );
define( 'SAVEQUERIES', true );

// Optional
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', true );

// Learn more: https://developer.wordpress.org/themes/getting-started/setting-up-a-development-environment/#wp_debug

Development Tools

We also recommend the following plugins and tools:

Note that these tools are meant for development/debugging only and should not be included in your theme or pushed to production.

Staging Environments

For staging environments, the only difference would be to use a hosting provider of your choice for your WordPress environment (some examples include DigitalOcean, AWS, and so on).

Personalization

As the audience of your website grows, it becomes more challenging to publish content that is relevant to all readers. Personalization gives you the ability to profile each user’s behavior and capture their preferences, allowing you to display more relevant content and ultimately, keep your audience engaged.

What is personalization?

Personalization can mean different things to different people but it mainly involves providing your audience with a more customized and engaging experience. It could mean that you’re providing content that is more relevant to their geographic location or that you’re providing them more relevant content based on what they’ve viewed or liked in the past. Personalization could also mean that your users are able to share content with each other and follow people or topics that they are interested in.

Considerations

Before diving into using the most popular plugins for personalization, there are a few items that you would want to keep in mind, regardless of the type of personalization that you’re interested in. 

  • Sending data to the personalization vendor: If the personalization requires you to send them any data (user data, activity data, etc.),  you will have to include a javascript snippet in all of your pages. Be sure to choose a reliable third party vendor as slow response times on their end could affect your end-user experience.
  • Serving recommendations from the personalization vendor: As the recommendations for a specific type of user may change, the recommended list of content is typically sent dynamically from the personalization vendor’s systems. Some vendors store the user’s behavior in a cookie so that your users don’t have to rely on their service being online but make sure you understand what features of your site (if any) will be impacted if the service vendor’s systems go offline.
  • Limiting the user information that is shared: If you require users to sign in with their account, you have the added advantage of using their historical preferences to personalize. However, this would require you to share additional information with the personalization vendor. It is best to let your personalization vendor know just the username or a separate unique identifier for the user.
  • Supporting cross-channel interactions: If you want the flexibility to capture data from your users across various channels (social media, email, mobile apps, website, etc.), you will need a vendor that can unify data from all of these channels to a single user profile (typically based on the email address). Most personalization vendors that support cross-channel data gathering will also let you publish your recommendations through any of these channels.

Types of personalization

There are no limits to how you can personalize your content but the most popular options include:

Customer Identity & Access Management

Personalizations rely heavily on understanding who your customers are. A sophisticated customer identity and access management solution will help you identify your customers regardless of the device or channel they’re engaging from, allowing you to keep your message consistent across a diverse platform.

Janrain, a Featured Partner of VIP, provides a platform that combines your ability to acquire users across multiple digital and marketing channels. In addition to providing a Single Sign-On solution, they provide a hosted user database and provide integration for social sharing.

We have also had VIP clients use Gigya, another popular platform to securely manage and update user profiles, thereby giving you a great starting point to provide personal experiences.

Custom Social Network

If you have built a community, you may be looking to empower your users to share stories, like each other’s’ contributions and have a newsfeed of updates from the people or things that they follow.

The popular BuddyPress plugin built by the WordPress community provides a lot of social network features out of the box. It provides both private messaging and public sharing. However, the vision of some of our clients were better met by using a Featured Partner for custom development.

Predictive Marketing

You might have noticed that some sites have a ‘You might also like’ section, listing content related to what you have been reading. There is another variant of this personalization where content related to the current page is listed. These dynamically shortlisted links are more relevant to your users and have a higher click-through rate.

One of our featured partners: Sailthru, is the leading provider of personalized marketing communications. Their WordPress plugin makes it easy to provide personalized content through their Scout and Concierge modules. Scout provides content relevant to a page whereas Concierge provides content that is recommended for the specific user. Under the covers, both modules use predictive marketing algorithms to determine the best recommendations for your users.  We have had multiple VIP clients use Sailthru’s straightforward integration to personalize their content.

If you’re looking to add a simple ‘Related Posts’ section to your website, WordPress.com’s Related Posts feature may be all you need. It’s powered by the popular Jetpack addon, which uses ElasticSearch to analyze your content and understand its relevance to the rest of your website. You can finetune how the recommendations are displayed using the customization options.

Geo-specific content

As your audience grows, you might find it challenging to provide content that is engaging to your users regardless of where they’re from. WP.com Geo Uniques allows you to target distinct geographic markets with different content. You also have the option of defining custom location groups so that you can target groups smaller than countries.

VIP Go FAQ

Below you can find shorter answers, which don’t warrant a documentation page to themselves (see our documentation for VIP Go), to some frequently asked questions about VIP Go. If you cannot find what you need to know here, or by searching, please feel free to contact us and we’ll be happy to help.

What version of PHP is VIP Go running?

We’re running 7.0.

Where do themes and plugins go on VIP Go?

You can add themes to the themes directory. You can add plugins to the plugins directory. Plugins can be activated in code using wpcom_vip_load_plugin. We have some remnant shared plugins in VIP Go currently, but we aim to remove them all soon; accordingly, you must include plugins you wish to use in your site plugins directory. A copy of a plugin in the site plugins directory will be used in preference to any copy in the muplugins/shared-plugins directory.

Can we add third-party plugins and libraries/SDKs inside the plugins directory?

Yes. These still need to go through code review. Note that you can use git submodules where the source repository is public, but we do not support private submodules.

How does deploying code work?

When you push changes to the master branch of your site’s repository, it will get pushed into a “deploy queue” here, where we review it before it goes out to production. There’s no need to open a ticket to request a deploy.

Do static files (CSS, images, etc) auto-deploy like they do on WordPress.com VIP?

No, there is not currently any automatic deployment of files based on file type. We may add this in the future.

Can I use capital letters in file paths?

Yes.

How does file concatenation and minification work on VIP Go?

VIP Go will concatenate both Javascript and CSS code and also minify CSS code. If you minify files in your theme, you should also include the source files for code review.

How does setting permalinks work?

You can set permalinks normally. Permalinks do not get flushed on deploy, instead you can include the Rewrite Rules Inspector plugin and use this to flush the rewrite rules.

Can we use the “www” version of a domain, or do we have to use the non-www/root version?

You can use the “www” version of a domain (and the root/non-www version will also work). You can set up any needed redirects directly in the `vip-config.php` file for your website, or from within WordPress. Please note sub-subdomains are not supported at this time.

When redirecting in the vip-config.php file, please omit the /cache-healthcheck? URI from your redirects. This URI is used by the VIP Go platform to check the health of your site, and a redirect response will cause issues with your site being served correctly. The code snippet below demonstrates how to avoid affecting the healthcheck when redirecting in the vip-config.php file:

if ( '/cache-healthcheck?' !== $_SERVER['REQUEST_URI'] ) {
// Put your redirects here, and they will omit our cache healthcheck
}

Can I get a SQL dump of my site?

You can log into VaultPress and get a SQL backup of your site. Note, it is required to remove the jetpack_options option before MySQL exports/imports into a local development or staging environment, otherwise this will create Jetpack issues on your production site.

How do I make a VIP Go site private and/or discourage search engines from indexing it?

We automatically add a Disallow: / robots.txt for sites using a go-vip.co domain, but otherwise do not handle blocking/managing access for private sites at a platform level. You’re welcome to include any plugins you want to use that meet your needs and that follow VIP code guidelines.

How do I enable sitemaps on VIP Go?

The MSM Sitemap plugin isn’t available on VIP Go by default, but you can use it as a git submodule if desired. The wpcom-sitemap.php plugin, which enables “news” sitemaps, is available via our shared plugins directory.

Is there asynchronous job processing on VIP Go like there is on WordPress.com? What about asynchronous exports for large sites?

No, there are not currently any asynchronous job processing options on VIP Go – all cron calls will be processed in core WordPress. If you have a large site to export, please open a support ticket and we can perform that for you directly.

Can WP CLI commands be run on VIP Go?

Yes, please open a support ticket and we’ll be happy to run WP CLI commands on your behalf.

Can I tailor the new user signup flow?

Yes, because each VIP Go site is a standalone install of WordPress with its own database, including the user table, VIP Go site owners are able to configure their own signup flow as they require.

How do scheduled jobs (Cron) work on VIP Go?

Scheduled jobs on VIP Go use the WP Cron API provided by WordPress core. The cron jobs are initiated and regulated via the WP Cron Control plugin. We trigger this on a one minute interval via HTTP request from our WordPress.com Jobs System.

How does SSL/HTTPS work on VIP Go?

A VIP Go site must have an SSL certificate installed in order to be active. Because every site uses a custom domain for both the front-end and admin area, and because we want each site to have a secure admin area and login process at minimum, SSL is a requirement. Read more about SSL on VIP Go.

Does VIP Go support HTTP/2?

Yes. HTTP/2 is supported and enabled for all sites hosted on the WordPress.com VIP and VIP Go platforms. HTTP/2 requires that SSL be enabled to work. We currently do not support the server push functionality of the HTTP/2 specification.

Can we have access to the filesystem to support a build process?

No. If you need to do a build one option is to use a CI tool like Travis to build from a working branch to the master branch, or similar, please contact us to discuss your requirements as this can complicate code review for your site.

Does VIP Go have the “protected embeds” feature from WordPress.com?

No. The WordPress.com VIP protected embeds feature is specific to that platform. On VIP Go there are two alternatives: (1) build shortcodes into the theme for the embeds you need (probably the safest option) or (2) implement your own protected embeds style solution for your site (here is a plugin used by some VIP Go clients for doing this).

User Security Best Practices

We encourage all users on VIP sites to follow best practices when it comes to securing their devices, accounts and access to VIP tools. Two-factor authentication is required for all users with the ability to publish to a VIP site and we also recommend following at least these basic steps:

  1. Set a login password for all user accounts on your computer.
  2. Set a complex (more than 4 character) passcode to unlock your mobile devices. Do not use fingerprints or patterns.
  3. Enable a screen saver that activates after a short period of time and requires a password to turn off.
  4. Use only strong passwords. Never use the same password in more than one place.
  5. Use a password manager such as 1Password or LastPass.
  6. Never put passwords in text documents, Google Docs, intranet pages, post-it notes or other unencrypted forms of storage.
  7. Use two-factor authentication for any services that support it, including WordPress.com accounts, Google apps such as Gmail, Dropbox, Twitter, Facebook, Github, iCloud, LinkedIn, PayPal and others. Do not store 2FA backup codes anywhere online.
  8. Turn on device locating services such as “Find My Mac” for Apple laptops or “Find My iPhone” for iPhones.
  9. Encrypt your computer’s hard drive, and make sure any backups are encrypted too.
  10. Install and run anti-virus software with the latest virus definitions.
  11. Enable your computer’s firewall.
  12. Ensure that your home and office network routers are running the latest firmware and aren’t using default passwords.
  13. Be suspicious of any unusual requests to share sensitive information, such as usernames, passwords or other personal data. Report any such requests and “phishing” attempts.
  14. If working in public, use a privacy screen to prevent your activity being seen.

If you have any security-related questions about your WordPress.com account, your VIP site or any related service, please contact us via support ticket.

Launch Checklist

Welcome to WordPress.com VIP Hosting! We believe that WordPress.com VIP is a partnership between WordPress.com and some of the most high-profile, innovative, and smart WordPress websites out there. We’re excited to have you here.

The following list provides general guidelines to launching a site on WordPress.com VIP. Please know that the guidelines may vary for your specific site.

1. Kickoff call

To get started, you’ll have a kickoff call with the VIP team, where you will establish your launch timeline and get access to all of your VIP Tools. If you have a large content migration, this is a good time to also begin planning your migration timeline.

Here’s a typical launch timeline:

  • 3 weeks: Your developers submit your theme for VIP Code Review. During this time, the VIP team will go through your theme line by line, giving you feedback on your code. Adhering to our Theme Review Guidelines and pre-auditing your code using our Code Review List can greatly speed up your review time.
  • 2 weeks: Your team works on fixes based on code review. This timeframe can vary greatly depending on what recommendations are made during code review.
  • 1 week: Content Migration and User Creation
  • 1 week: QA and final cleanup
  • Launch!

2. Get acquainted with documentation and plugins

You and your development team should explore our Documentation site and get familiar with coding for WordPress.com VIP. Good pages to focus on:

3. Send us the list of plugins you’d like to use

WordPress.com has hundreds of features built right into the platform which would normally require plugins for self-hosted sites (self-hosted sites can use these features via the Jetpack plugin). WordPress.com VIP sites have access to dozens of pre-approved, shared VIP Plugins.

By sending us a list of plugins you intend on using, we can help map your site’s needs to existing features or plugins, suggest more performant alternatives, or flag issues with proprietary plugins if no alternatives exist.

If you are interested in using a plugin that isn’t available as a pre-approved VIP shared plugin, we will review it for stability, performance, and security before it can be used on WordPress.com. The plugins must fit within our recommended plugin guidelines for the safety, security, and scalability of your site.

4. Set up your WordPress.com site

Set up a free site on WordPress.com, prefixing the subdomain with your company name (example: nbcsitename.wordpress.com). Be sure to mark the site as private. The WordPress.com subdomain you create will only be shown in the dashboard – since we’ll be mapping your domain, your visitors will see your branded/official URL. Once you’ve set up the site, let us know via VIP Support and we will mark it as VIP, which will enable the VIP Dashboard and VIP privileges for the site. When your theme is reviewed and ready for production, we will enable the theme on this site as well.

5. Submit your theme for Code Review

During the code review process, our engineers review your theme line by line, seeking out security holes and optimizations. It’s important to note that this process can take 10-15 business days, so please plan for this time in your project schedule. Before submission, it’s essential that your development team has read our Code Review document and check their code for Blockers.

And, if your development team has questions at any time, please encourage them to open up a ticket. We are always happy to help answer questions.

6. Start adding users to your site

Once your WordPress.com site is set up, you can start adding users to your site. Each user will have a WordPress.com account to access the dashboard. If there’s a small number of users (15-20), you may want to add them yourself. If it’s a large number of users, we can help add them for you. More information on adding users here.

7. Get ready for content migration

As you’re ramping up towards launch, you’ll want to plan out when you will begin importing content. For small migrations (less than 15MB), you can use the Import Tool in your dashboard to complete the import. For larger migrations, we may help you bring in the content, but it should be converted into a WXR format first. More information here.

8. Get your developers access to your code

We review every line of code that gets committed to your site for security and performance before deploying (with the exception of CSS, which gets deployed instantaneously). Roughly 90 percent of commits are deployed within 2 hours.

After your theme has been reviewed, your developers will be able to use their WordPress.com username and password to access the code for the theme using subversion. To get access, your developers must put in an SVN Access Request through the VIP Dashboard.

If you are working with a Featured Partner, this step will not be necessary as they will already have SVN Access.

9. Mapping Your Domain and Managing DNS

Please share with us early on what the final URL of your site should be.

Roughly two weeks prior to launch, you’ll want to get in touch with us about mapping your domain. Typically, you’ll send us your domain’s ZONE files, which we will mirror. Once that’s all set up, we’ll tell you to point your nameservers to WordPress.com, and since we’ve mirrored the ZONE files, everything will stay the same.

It’s very important to have the nameservers switched 1-2 weeks before launch (if using the WordPress.com nameservers) to ensure a smooth transition.

If you are required to host DNS elsewhere, please make sure your DNS host can support multiple A records.

On your launch day, we will update your site’s entry to point to your new site. Technical details and step-by-step list here.

10. Launch!

At this point, your theme will be approved and enabled on your site, your users activated, your data migrated, and your nameservers pointing to WordPress.com. In the week before launch, you’ll want to communicate the exact launch time you are looking at so that we can help flip the switch and make sure developers are around for any last-minute needs.

Here’s a typical launch process:

  • Notify VIP Team: Communicate to the VIP team early your anticipated launch date. Our preferred launch days are Tuesday, Wednesday, and Thursday. Since launch times and dates tend to shift, roughly 30 minutes before launch open an urgent ticket with the VIP team to let them know you’re ready to go.
  • Set your site as public: It’s very likely you set your site to “Private” before launch. Be sure to set your site to public so that your visitors can access it! Also, make sure that your robots.txt file is listing the correct records.
  • Point to WordPress.com: If we are hosting your DNS, we will do this for you. If you are hosting your DNS, you will have to do this to launch. Please be sure to confirm these changes with your IT team ahead of time. More information.
  • Set your primary domain: Navigate to VIP > Domains in your dashboard and set up your Primary Domain. This will make the correct custom domain displays to users. Verify that legacy redirects working as expected.
  • Keep in touch: If there are any issues, please open an urgent ticket and we will assist immediately.

Accessing Your Code

All WordPress.com code is managed using the Subversion revision control system. Subversion (SVN) is the only way to access and update code on VIP Hosting.

If you are a Microsoft Windows user, we recommend using the TortoiseSVN GUI client. If you use a Mac, and you don’t grok a little UNIX, SVNX comes recommended.

Accessing SVN

To get SVN Access to your theme, please first make sure you have Two-Step Authentication enabled.

Two Step Authentication drastically reduces the likelihood that someone could gain unauthorized access by adding a second, very hard-to-guess log in requirement to your user account. To learn more about Two Step Authentication, read the support page or contact VIP.

Once that’s all set, you can request for SVN Access via your VIP Dashboard, under the “VIP” tab:

Once read-write access has been granted, you’ll receive an email with the subversion repository URL, which is specific to your site. You’ll also receive read access to our shared VIP plugins. For more details about our shared plugins, please see the plugins section of this site.

All code development and testing should be done in your own local development environment. Only tested code should be committed to WordPress.com.

Committing Code

Once you have read-write access, you can commit your code directly. Once you do, it is spot reviewed for security and performance concerns, and then deployed to server clusters in all of our data centers. Should you not want the commit to be deployed directly after a satisfactory review, please follow the instructions for how to schedule your deploy.

For your benefit, we take code quality, security, and performance very seriously. Every commit is spot reviewed by someone on the VIP team before it can be deployed. It’s really important to include a detailed commit message to help expedite your review. Please take a look at our deploy review guidelines. Code changes are usually deployed within a few hours during US business hours, but usually much faster (within two hours).

We do expect all committed code be thoroughly tested and follow our best practices guidelines. If we see repeated mistakes, we will revoke write access.

Please check with us before committing very complicated or large chunks of code. As a general guideline, commits should include fewer than 1,000 lines of changes or modifications to PHP and unminified JS.

If in doubt, it’s best to check with us first by submitting a ticket.  It’s a lot less work for everyone (including you) if we’re able to take a look at it before committing than having to revert the change later. We also greatly appreciate if you commit often and with each functionality as a separate commit (if possible) rather than waiting and pushing a bunch of code to us all at once. It makes the code easier to review if we’re reviewing things in chunks.

We also like to review all plugins prior to committing them to your VIP repo. We have reviewed a small, but growing list of plugins, and modified some of them to make them more stable, secure, and perform better. Since these plugins have been pre-approved, we would prefer you use these plugins if possible if you need functionality similar to what they provide. Please see the Plugin Review Process if a solution isn’t yet available.

File Types That Are Auto-Deployed

We auto-deploy commits that consist entirely of static CSS or image files. If there are no other pending deploys for your theme, your CSS design changes and image commits will be deployed almost immediately with no review. If you want to ensure that a commit is auto-deployed, be certain that it only contains the file types listed below and does not have any non-auto-deploy commits in front of it. It’s worth noting, too, that even adding a new directory to a commit will prevent it from auto-deploying. So if you commit all image files inside a newly added directory, that commit will not auto-deploy.

File types that auto-deploy:

  • png
  • jpg
  • jpeg
  • gif
  • ico
  • svg
  • css
  • less
  • sass
  • scss

Note: JavaScript is not auto-deployed.

Deploy Status

At VIP → Dashboard (/wp-admin/admin.php?page=vip-dashboard), you can see the current deploy status.

Commit Messages

All commits on the VIP repo should be accompanied by a Good Commit Message.

Reverting Code

A detailed document on how to revert via svn can be found here, Rolling Back / Reverting Changes to Your Theme Using Subversion.

If you’ve committed code you’re not happy with and would like to revert, you can do so from your local checkout. Simply use the command “svn merge -c-64320 .” where “64320” would be the revision you’d like reverted. After running that command, you’ll need to commit your revert. You’ll want to use a commit message similar to “Reverted r64320 because [explain your reasoning]”.

Note that the revert will need to be deployed as well and you can open a ticket requesting that.

Shared Accounts

We don’t allow generic usernames or shared user accounts to have write-access to your VIP code repositories, as it obfuscates which developer wrote the code in the first place, and also encourages insecure password management. Please use a unique user account for each developer on your team.

Occasionally VIP development teams prefer to have a single lead developer responsible for managing their team’s code and committing to VIP on their behalf. We would like to know if this is the setup you are using and who the lead developer is. We’re happy to support this workflow so long as the person committing is themselves a developer, and takes responsibility to review the code against our guidelines before committing. If that isn’t happening, and/or we see repeated issues around code quality, we’ll need to insist that each of your developers have separate VIP accounts and support seats.

Commit and Deploy Notifications

When a code commit is deployed to WordPress.com, an email notification is generated to every WordPress.com user who has access to the theme’s SVN repository.

In addition, we support the use of webhooks for both commits and deploys. These allow you to customize the kinds of endpoints you use to receive notifications about activity in your theme code. Note that these only work for theme repositories, not shared plugin repositories.

Introduction to the VIP Review Trac

We use the VIP Review Trac for all theme and plugin reviews. Our goal is to help you produce better quality code and improve the likelihood of launching in a timely manner.

Trac Overview

The VIP Review Trac is a standard Trac install with extra VIP juice mixed in. If you haven’t used Trac before, it’s an open source wiki, issue tracking system, and code browser that integrates fully with Subversion, our version control system. Because it also has a plugin architecture, we’ve extended it to include features like inline code commenting.

Trac is also the primary project management tool for the WordPress.org project. We’ll hope you’ll give back, either by writing patches for tickets, testing others’ patches, etc., once you become more familiar with the WordPress software.

Code Reviews With VIP Review Trac

When a VIP sends in a new theme or plugin via support ticket, we’ll load the code into the VIP Review Trac and send you a link to make the code review process more collaborative and effective. We’d like the review process to look something like this:

  1. A WordPress.com VIP Team member commits the initial set of code, and grants read-write access to VIP developers/project managers. You’ll be able to authenticate using your WordPress.com account. From this, you’ll be able to check out a copy of the code, browse the code in Trac, and see all of your tickets (assigned or cc’ed) from the homepage. You’ll also want to set your email address in Trac preferences so you receive notifications for new tickets or comments.
  2. WordPress.com VIP reviews the code, leaving inline comments and creating new tickets as needed. You can start working on issues as soon as we open them, but we’ll let you know when the review process is complete.
  3. We start everyone off with read-write access to code in the VIP Review Trac so you can resolve the tickets in a timely manner. The order in which you resolve the tickets does not matter, but we expect that each commit to the repository can be linked to only one or more tickets, if possible. You can do so with “See #NN”, “Ref #NN.” Also, please keep your commits as small as possible and make sure your commit comment communicates the change well. When you’ve committed all of the necessary code to resolve the issue, you can close the ticket.
  4. Once all of the issues are resolved, we’ll move the theme or plugin to WordPress.com. At this time, you should switch your Subversion checkout to the new VIP Subversion URL and prepare all future patches against that checkout.

As always, we love all feedback on what works and what could be improved.

Code Review

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:

  1. Theme Review: You are launching or redesigning your site, which means you will submit a complete theme to us (with plugins included).
  2. 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.
  3. 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

  1. Development Environment: Make sure your local development environment is set up correctly, as described here.
  2. Code Review Guidelines: Make sure to read all the code review documentation. The what we look for page is a great start.
  3. 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.
  4. 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.
  5. WordPress Standards: We recommend all developers follow  WordPress Coding Standards. It ensures consistency, code cleanliness, and speeds up a review.
  6. 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 VIP Scanner, 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 handing 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 query_posts().
  • All custom functions are prefixed.
  • The 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 VIP Scanner (required):

  1. What date are you targeting to have this code launched? Please allow sufficient time in your schedule for our review and launch process.
  2. Please provide a 1-2 sentence description of your submission.
  3. Please provide a brief architectural overview of your code.
  4. 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.
  5. Is this code based off of existing code? If yes, provide specific details (eg: “includes code from XYZ project…”)
  6. Does this code run successfully in a local development environment?
  7. Has this code been ran through the VIP Scanner, and have all blocker-level issues been addressed and other errors closely investigated? You’ll need to upload scanner results along with your submission
  8. 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.
  9. Which URL do you intend to use for this site? (We do not support the www subdomain, or mapping domains to a subdirectory)
  10. Is the theme named correctly?
  11. Does this theme follow the WordPress coding standards?
  12. All custom functions must be consistently prefixed. Which prefix did you use?
  13. Does the themes root directory include the functions.php and style.css files?
  14. Is vip-init.php included at/near the top of functions.php?
  15. Are scripts and styles are enqueued, and done so on the proper hook?
  16. Is the vip_powered_wpcom() function called in the theme’s footer.php?
  17. Does the 404.php contain any database queries?
  18. Is there a “plugins” sub-directory at the theme root?
  19. Which plugins does this theme use?
  20. 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.
  21. 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.)
  22. Are there any significant features or components that are to-be-developed before launch, but not included in this initial submission?
  23. 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 wp_handle_upload().
  • 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 functions.php. e.g.:

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 wekends, 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.

Migrating and Importing Content

It’s important to start populating your site with real content as soon as possible.

For Small Migrations (less than 15MB)

We make it easy for you to import your blog content from your self-hosted WordPress site, as well as a variety of other blogging platforms, including: Movable Type, Blogger, Tumblr, Typepad, LiveJournal, Posterous, Yahoo! 360, Israblog, and Splinder. Simply log into your WordPress.com dashboard, then go to Tools -> Import, choose your previous platform and follow the instructions. The WordPress.com support site has more detailed instructions, or feel free to reach out with any questions.

Please note that this method only works for migrating standard post types. If your theme includes Custom Post Types, you will need to use the method outlined below.

For Large Migrations

In most cases, the most straightforward approach to migrating your content is to first get it into WordPress’s native import/export format: WXR. Once you have all of your content available in WXR format, WordPress can import that file. Please make sure your source site is publicly accessible as our importer fetches media files over the web. Here’s a rough outline of how most content migrations work on WordPress.com VIP.

1. Preparing for Migration

The first step in preparing for your content migration is informing the WordPress.com VIP team of what to expect. To do that, please fill out and submit this questionnaire via the VIP Support Portal:

  • How many posts, pages, images, and comments are in this migration?
  • What’s the combined file size of all your media assets? This helps us estimate approximate import time.
  • How many users are in this migration? How many of them require “real” WordPress.com accounts with login access, and how many of them require “guest” accounts with no login access?
  • Are there any custom post types that we should be aware of?
  • Are there any custom taxonomies we should be aware of?
  • Are there any special considerations or requirements for redirects that we should keep in mind?
  • Are there any special considerations for content segmentation (i.e. different languages)?
  • Is the site content ready to go live, or do you plan on doing edits and cleanup post-import?
  • By what date will you be able to get the full export to us?
  • By what date do you hope to have the full import completed?

2. Staging content

In preparing for the migration, your team will need to prepare, QA, and stage all the content. It’s very important that all content cleanup is done before the import is run, because running fixer scripts on WordPress.com VIP can be time consuming and delay launch.

3. Get Your Authors Access

In order for us to properly attribute your content, you will need to get your authors, editors and administrators WordPress.com logins to access your site. Here’s more information on how to do this.

4. Mapping Bylines

Once all the authors are created, we will need to make sure that the bylines from your old site will match on your new site. Here is more information on how to create a mapping document, and how to deal with bylines that don’t require logins.

When you submit your WXR export to us, we will use this mapping CSV to make sure that the bylines are properly attributed.

5. Import QA

To determine that your content is ready for import into production, please answer the following questions when you submit your WXR to us:

  • Have you verified that your author map is properly formatted? We need the CSV in old_user_login, wpcom_user_login.
  • Do all the users that need a wpcom login exist in your WordPress.com wp-admin?
  • Have you verified that your author map is correct? Are all authors listed, and properly mapped?
  • Is the author list complete? Will there be more users added later?
  • Who should the “fallback” or “default” user be, if the post does not have an author?
  • Is inline content correct (i.e. content inside the post_content column)?
  • Are shortcodes and embeds working properly?
  • Have you completed a find and replace for any old URLs?
  • Have you properly QA’d all your redirects and gathered any URLs that need redirecting?

6. Running the Import

Once the theme has been through code review and enabled on your WordPress.com site, we will be able to run the import. You can submit the WXR file to us via Dropbox or another download location via our Support Portal.

Please make sure that your source site is publicly accessible, as our importer fetches media files over the web, and if the site is password-protected we won’t be able to reach them and they will not be imported.

Importing to a live production site

To ensure a smooth import when importing to a live production site, we first run the import to a temporary, private VIP-hosted instance running your theme. This makes it possible to proceed with Step 6, QA Content, in a private environment before pushing the data to production.

Once everything is completely QA’d, fixed, cleaned up and approved on the pre-production instance, we can safely run the import to production without the risk of breaking things on your public site.

Importing in parallel with Theme Review

If your project is moving quickly, we can begin the import in parallel to your code review. If the theme utilizes custom post types and taxonomies, we will ask you to submit an Import Theme.

How to create an import theme

The Import Theme should be a completely stripped down version of the theme slated for production and should include no more code than the following:

  • Loading vip-init.
  • Loading any necessary VIP plugins.
  • Registration of custom post types and taxonomies (including ones extracted from in-theme plugins).
  • Any import-related code.

Most import themes are no more than a few hundred lines of code, consisting primarily of “register_post_type” and “register_taxonomy” calls.

7. QA Content

Once the import is complete, we will notify your team. At this time, your team must check through the content carefully to ensure that nothing is missing. Things that should be included on your QA list:

  • Checking media files.
  • Ensuring that shortcodes and embeds work.
  • Making sure that authors are properly mapped.
  • Making sure that all download media links work.

We strongly recommend that your team include time for content QA in your launch timeline.

8. Delta Import

Shortly prior to launch, we will help you run the delta import, which will contain all the content between the last export up until launch day. Typically, site editors should expect to double post content on both old and new sites for one day.

Note: Delta imports don’t overwrite previously imported content, so any changes to old posts will also need to be mirrored to WordPress after the initial import.

8. Launch!

Migration Services

Migrating content from WordPress-to-WordPress is included in your per-site setup fee. We also provide content migration services, and can help you migrate from any other content management system—those projects are priced on scope, and typically range $25k-$75k. Get in touch if you are interested.

Adding Users and Content

Adding Users

For editors, authors, and administrators who need access to your dashboard on WordPress.com VIP, they will need to have WordPress.com accounts. There are a few ways to do this:

If you have less than 20 users
You can easily invite users to your site via email. If they already have a WordPress.com account associated with that email address, they will be added, if they don’t, this will prompt them to create one.

If you have more than 20 users
You can ask your users to first create a WordPress.com account. Then, send us a spreadsheet (or CSV) with each user’s WordPress.com username, the role (“administrator”, “author” or otherwise) they should have, and the URL for the sites they need to be added to.

We prefer you ask your team if they have existing WordPress.com user accounts first, and to provide them to you if they do. In many cases, they may have already signed up for them and this will reduce confusion in the long term to just use one account across all of their WordPress.com sites.

Tip: We have an “Editor’s Guide to WordPress.com VIP” resource page that provides helpful links for new VIP authors and editors.

Preserving Bylines and Authors During Migration

First, be sure to look through our Migrating and Importing Content documentation.

Once all the authors are created, we can now safely migrate over content while preserving authorship of posts. To do this, you will create an author mapping CSV, mapping the username on your existing site to the WordPress.com username.

When you submit your WXR export to us, we will use this mapping CSV to make sure that the bylines are properly attributed.

For bylines that do not need logins, we recommend using Co-Authors Plus to create a Guest Author account. A guest author account allows you to create a byline with a bio, avatar, author page, without creating a login. This is ideal for one-off writers or folks who never login. Co-Authors Plus allows you to easily manage authors while decreasing the number of logins to your site (which can present a security concern). There are also wp-cli tools available to help create guest authors in bulk automatically.

Roles and Permissions

Users can have different permissions regarding creating, editing, and modifying site content. We suggest reviewing WordPress User Roles and select the appropriate permissions for that new user. Roles can be changed at any time by a site administrator.

For more fine-grained control, you can also create custom roles or modify the default ones.

Ready to get started?

Tell us about your needs

Let us lead the way. We’ll help you select a top tier development partner. We’ll train your developers, operations, infrastructure, and editorial teams. We’ll coarchitect your deployment processes. We will provide live support for peak events. We’ll help your people avoid dark alleys and blind corners, and reduce wasted cycles.