Related Posts

You can take advantage of the WordPress.com Related Posts functionality to return related posts quickly. Enable it by turning on Related Posts in Settings > Reading and you’re done!

If you’d like to programmatically retrieve and display posts within your theme code, you can do so like this:

$posts = Jetpack_RelatedPosts::init_raw()->get_for_post_id( $post_id, $args );

// Returns an associative array in the form of id => $post_id:
/*
array(
    array ('id' => 12345),
    array ('id' => 54321),
)
*/

Related Posts indexing will work regardless of whether your site is marked as “Private.” For self-hosted sites, Related Posts will currently only work for standard post-types; we are working on enabling it for custom post types.

For more information about ways to customize related posts, see http://jetpack.me/support/customize-related-posts/

High Traffic Alert

On WordPress.com, we serve 100+ million pageviews per day without blinking. However, sometimes you may be expecting a high traffic event where you may want to notify the VIP team for additional assistance.

To do so, please open a ticket with us with the following information:

  • Date and time of event:
  • Traffic expected:
  • Heavily trafficked pages:
  • Are there any external services, dependencies, or applications that use or rely on the site (e.g. mobile apps)? If so, how do these services interact with the site?

On VIP, we review every line of code to ensure that your site will perform under high traffic events. When you send in a high traffic alert, we will check through the theme again to ensure that it is performance-ready. Please notify us of the high traffic event as far in advance as possible so that there is enough time to resolve any potential issues.

As always, should you need our team immediately, please open a ticket with the word “urgent” in the subject line.

Creating Good Changesets

Changesets are the heart of any version control system, and making good changesets is vitally important to the maintainability of your code. As all code on WordPress.com VIP is reviewed by a real person, it’s even more important all changesets are well crafted.

Remember always code (and commit) for the maintainer.

A Good Changeset:

Represents one logical change

What comprises a ‘logical change’ is up for interpretation, but only directly related changes are included. Generally, the smaller the changeset, the better.

Good Example: Adding the CSS, JS, HTML, and PHP code for a new UI button.

Bad Example: Adding the new UI button, fixing whitespacing, and tweaking copy in the footer.

Bundles related changes together

It’s much easier to trace refactorings and other changes if related changes are grouped together. Rather than splitting a logical change into many separate commits, related changes should be combined.

Good Example: Refactoring code into a new plugin by moving it to a new file and including that file.

Bad Example: Refactoring code into a new plugin by putting the code removal, addition, and include into separate commits.

Is Atomic

An atomic commit means that the system is always left in a consistent state after the changeset is committed. No one commit would cause the codebase to be in an invalid state. The commit is easily rolled back to a previous valid state, including all related changes, without the need to analyze the potential interdependencies of neighboring commits.

Good Example: Adding a new feature to the homepage by committing the HTML / PHP changes alongside the required CSS / JS changes, so there is never an incomplete state (HTML elements without styling) in the codebase.

Bad Example: Committing the HTML changes and requisite CSS / JS separately. The first commit represents an inconsistent state, as the feature can exist in the DOM without being properly styled.

Is Properly Described

Accurately describing the changes is very important for others (and future you) looking at your code. A good commit message describes the what and why of a change. Please see Writing Good Commit Messages for more information.

User_meta vs User_attributes

User Meta

As you read in our what we look for documentation, we don’t allow the use of user_meta. The reason for this is that WordPress.com is an incredibly large multisite and user_meta is all stored in one cache key. Therefore anything stored in user_meta will be loaded on every page load. Another reason is that as the user_meta grows to over 1MB it can no longer be stored in memcache.

User Attributes

User_attributes are a drop in replacement for user_meta. They perform in exactly the same way with the small exception that you cannot have multiple values for the same user_attribute meta_key. You can find the function declarations in vip/plugins/vip-do-not-include-on-wpcom/wpcom-functions.php. These are functions that imitate the behavior of user_attributes on your local dev environement. This means you can code against them without needing to have the cache or table schema that runs on WordPress.com.

While the code you will see in that file looks just like a layer on top of user_meta on WordPress.com, user_attributes are stored in the cache on an individual basis and not globally. This means that requests to user_attributes by meta_key and user_id are cached individually and not grouped by user_id and loaded all at once per page load.

You can use user_attributes as a drop in replacement for user_meta. That means:

update_user_attribute( $user_id, $meta_key, $meta_value )

get_user_attribute( $user_id, $meta_key )

delete_user_attribute( $user_id, $meta_key, $meta_value = ” )

will all work as expected. Just remember, the meta_key are shared among all of WordPress.com so prefix them. As with user_meta you shouldn’t store large quantities of data (several KB), and lastly, since just like user_meta meta_key or meta_value on user_attributes isn’t indexed you shouldn’t query against them.

Custom Error Pages

We have error pages that are standard and served for all sites on WordPress.com, and as a VIP customer you can override these defaults and specify your own custom error pages instead.

Setting it up is simple: all you need to do is add a custom error page (a simple HTML file) to your theme.

The file needs to be located in a folder called “error-docs” and named “error-page.html”. Note that the file can only contain HTML and basic inline or remote-hosted CSS and Javascript.

I.e., from the root of your theme: ~/error-docs/error-page.html

Once you’ve committed the file to your theme, you’ll need to open a ticket with our team to notify us, so we can make some associated configuration changes on our end.

Editor’s Guide to WordPress.com VIP

Welcome to WordPress.com VIP!

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.

This page is to help managers and editors onboard their editorial team onto WordPress.com VIP. It includes information and resources to help you train your team. If you have any questions, please don’t hesitate to contact us through the VIP tab in your site dashboard.

Training Resources

Useful Features for Editorial Teams

Useful VIP Plugins for Editorial Teams

Advanced WordPress.com Features for Editors

Learn from WordPress Experts

Developer’s Guide To WordPress.com VIP

Welcome to WordPress.com VIP!

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.

This page is to help developers prepare their code for WordPress.com VIP. It includes information on how to set up a site on WordPress.com VIP, and how to communicate with the VIP team. As always, if you have any questions, please don’t hesitate to contact us through the VIP tab in your dashboard.

Getting Started

Quick Links

Important Documentation

Helpful Resources

Learn from WordPress Experts

Site Owner’s Guide To WordPress.com VIP

Welcome to WordPress.com VIP!

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.

This page is to help site owers and project managers navigate the world of WordPress.com VIP. It includes information on how to set up a site on WordPress.com VIP, and how to communicate with the VIP team.

A call with the VIP team kicks off the collaborative process. We review your launch timeline and introduce you to the VIP platform and development tools. We are happy to use this time to consult with you on the best setup, plugins, and tools for your site’s needs.

Next, we set up access to some of the tools and documentation spaces that we use, as well as send out questionnaires covering more detailed technical aspects on your content migration, theme and plugin requirements. This is then followed up with a technical meeting.

At this point developers need to start setting up their development environments which involves setting up your local environment, enabling the VIP code scanner and setting up the development IDE to support WordPress coding conventions. The scanner is an essential tool and will help developers to produce secure and performant code.

Next, you will build your website using one of our themes or alternatively start from scratch most likely using a starter theme. You will also integrate custom plugins or leverage our pre-vetted library of community and partner plugins.

We then review the theme and work with your team on any possible issues. Once any issues have been corrected, the code is submitted to SVN / Git (depending on your platform) and your developers or partner developers are given access. From this point onwards changes to code are made via the deploy queue. On WordPress.com CSS changes are deployed immediately with other changes being deployed after review by one of our developers

Please be aware that the initial theme review can take between ten and fifteen days and it is essential that the code passes the VIP scanner before submitting to us. If there are blockers in the code, theme review will be delayed.

At this stage we should know your user and content migration plans and the requirements for SSL will also need to be figured out. We will also work together to establish your final launch date.

The content migration must be carefully prepared and we will work closely together on making this as clean as possible. Please keep us up to date with changes to the content migration timeline as delays here can threaten the launch date.

On launch day, our team schedule engineers to be around to assist your team in realtime. We usually have a live chat open with your team to help ensure a fast response time for any last-minute questions or needs. We look forward to having a successful launch with you!

Getting Started

Quick Links

Information for Your Team

Learn from WordPress Experts

Cloud Hosting FAQ

Frequently-asked questions about our VIP Cloud Hosting. Have a question that’s not answered here? Get in touch. 

1) We don’t yet have a WordPress theme – how should we get started with WordPress.com VIP Hosting?

If you’re building a theme from scratch, we suggest using the WordPress default themes, Twenty Ten, Twenty Eleven, or Twenty Twelve, as they use the recent APIs, are cleanly coded, and provide a good foundation for your work. You should start your theme as a Child Theme instead of modifying Twenty Ten/Twenty Eleven/Twenty Twelve directly. All WordPress.com public themes are available at https://wpcom-themes.svn.automattic.com/.

2) We already have a theme on a self-hosted WordPress site. Will we be able to use it on VIP Hosting?

Yes, probably! As part of the setup process the VIP team will review your theme for any errors or code that needs to change to make sure it’s a good fit for our environment. We also require the use of GPL-licensed plugins and themes or 100% custom ones. If you’re not sure about what you’re using, just ask!

3) How long does the theme review process take?

Once you have your theme fully built and tested in your local environment, the theme is ready for us to review. We generally need 10-15 business days to do a full theme review. You’ll send it to us in an email as a zipped attachment.

4) Can we use X plugin?

Yes, probably! There are +23k WordPress plugins, and you can use most.  We review each plugin to be sure it’s enterprise quality, secure, and will scale with your site’s traffic.  Legacy methods of modifying database tables and manipulating the file system are also traits of plugins we try to avoid, and will work with you to use modern approaches such as Custom Post Types and in-memory file manipulations. We also have a bunch of popular plugins already pre-installed and ready for use. If you are interested in using a plugin that isn’t available as a pre-approved VIP plugin, we will review it for stability, performance, and security before it can be used on WordPress.com VIP.

We also recommend using existing WordPress functionality whenever possible instead of a plugin. If you are not sure if a function exists, try a quick search of a descriptive keyword/field name or similar on one of the many WordPress code documentation sites such as https://developer.wordpress.org/http://phpdoc.wordpress.org/trunk/, http://wpseek.com/, or http://hitchhackerguide.com/function-filter-action-index/

5) Can we use X caching plugin?

You won’t need any caching plugins on WordPress.com VIP Hosting. WordPress.com employs multiple levels of caching automatically. For cases when you are sure that you cannot use a function that contains caching and need to do something that is resource intensive, you should implement some caching yourself using the WordPress cache.

6) How will we access our code?

All WordPress.com code is managed using the Subversion (SVN) revision control system. SVN is the only way to access and update code on VIP Hosting. After your theme has been reviewed, you will be able to use your WordPress.com username and password to access the code for your theme using Subversion. The VIP team will review and handle all deploys for your site, and your developers will get deploy notifications automatically.

7) How does staging work?

VIP clients for the most part have staging servers in-house. A few clients choose to use one of their VIP-package sites as a pre-production site, but any code must be tested and debugged prior and aligned with our coding standards. Think of this pre-production site as a way to test integrations with WordPress.com features that don’t have WordPress.org equivalents (via Jetpack or other plugins).

8) Can we have custom database tables on WordPress.com?

Themes and plugins should use the existing database tables and structure (no alterations). Custom Post Types, Custom Taxonomies, post meta, etc. are incredibly flexible as an alternative to custom database tables.

9) Can we use plugins or code that modify the filesystem?

For security and performance reasons we do not allow plugins or code that write directly to the filesystem.  We’ll work with you to modify the code to avoid local file system manipulations.

10) How do we register user accounts?

By default, users registered through VIP-hosted websites are created as WordPress.com users, which means that the millions of users logged in to WordPress.com will also be logged in on your domain, making it easier for them to comment on your site. If you’d like to be able to query user data or create custom registration fields you’ll need to use a 3rd-party registration service.

11) Is WordPress.com VIP running stock WordPress, or are there tons of custom modifications?

WordPress.com is running mainly off core WordPress, but uses some alterations and optimizations which are unique to our large-scale environment, including a lot of very cool features built right in for all users. WordPress.com is constantly evolving, which means that VIP clients often have access to the latest features and WordPress releases well before the rest of the world. Easy-to-use shortcodes and other built-in features replace the need for many custom plugins.

Have a question that’s not answered here? Get in touch. 

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.

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.

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.