Category Archives: Doc Updates

Now Available: An easier way to test Jetpack releases

We’ve deployed a new way to test different Jetpack versions on VIP Go sites.

By default, VIP Go will load the current stable version of Jetpack from the MU plugins directory. Using the VIP_JETPACK_PINNED_VERSION constant, you can instruct VIP Go to load a specific version of Jetpack, maintained in parallel in the MU plugins directory Simply add the constant with the version number you’d like to the site’s vip-config.php file.

define( 'VIP_JETPACK_PINNED_VERSION', 'x.y');

Note that sites can only be pinned to minor (x.y) versions. For example, if you want to test version 9.0-beta, just use 9.0 in the constant. When 9.0 is released, it will be updated automatically. Point releases containing security patches and/or bug fixes will automatically be applied to each version.

You can find more details about this in our documentation. If you have any questions, please file a support ticket and our support team will be happy to assist you.

Support Documentation Updates: Q1, 2019

This notice relates to the following platforms: VIP Go

This post highlights some of the recent changes and additions to our support documentation.

Documentation architecture updates

We heard your feedback, and have been working to make the process of navigating our documentation easier. Starting from the docs landing page, you’ll find a more informative schema to help you find everything you’re looking for. Check it out!

New and updated documentation

We’ve published a new series of documentation for developing with VIP, which walks you through all the main topics to know about developing a site for VIP. This series introduces developers to our tools and processes, providing a path through our developer-specific documentation.
A new addition to our docs is information about the new Cache Personalization API. This API provides an easy way to customize the caching behavior of the VIP CDN, allowing personalization and segmentation of your audience without sacrificing stability and performance.
We’ve updated our docs on syncing production databases to child environments, with the exciting addition that it’s now possible to generate YAML config files from the VIP Dashboard. More info in our documentation.

As VIP continues our work on improving and expanding our support documentation, we’ll post regular updates about new and updated docs.

If you have questions or feedback about any of our documentation, please get in touch!

Support Documentation Updates: December edition

This notice relates to the following platforms: VIP Go

This post highlights some of the recent changes and additions to our support documentation.

New documentation:

We’ve published a new series of onboarding documentation for launching with VIP, which walks you through everything that would be discussed on a kickoff call. The goal for this series is to provide clarity about the launch process, and to provide a path through our documentation for clients who are in the pre-launch phase.
There’s a brand-new page all about Single Sign-On, including tips on setting up some of the more popular solutions.
If you’ve ever wondered how to retire a site from VIP Go, we now have a page for that, too.

Updated documentation:

We’ve updated our docs on installing and activating plugins, to clarify the distinction between the plugins and client-mu-plugins directories.
Our docs on using sunrise.php have been expanded, with more examples and guidelines.
We’ve added more details around testing CircleCI into our documentation on the automated build and deploy process.
The docs on the Fieldmanager plugin have been expanded to include tips and examples for creating different types of fields.

As VIP continues our work on improving and expanding our support documentation, we’ll post regular updates about new and updated docs.

If you have questions or feedback about any of our documentation, please get in touch!

Support Documentation Updates

This notice relates to the following platforms: VIP Go

Over the last few months, VIP has been working on improving and expanding our support documentation. This post highlights some of those changes.

New documentation:

We added a page of documentation to help you interpret the feedback given by the VIP Code Analysis Bot. The new bot is running on all VIP Go repos in GitHub, and gives automated code review feedback on PRs.
For clients with sites on Standard-level review, we have a new documentation page to help interpret VIP’s feedback on your codebase.
We’ve published a new page all about best practices in JavaScript security.
An index page of all VIP Go documentation.

Updated documentation:

We revised the docs on code review to reflect the new levels of review available on VIP Go.
Our docs on importing content into your VIP Go site have received an overhaul, with updates to help clients prepare their files for migrating into sites on VIP Go.
We’ve added more information on how the VIP Go filesystem helps to keep VIP Go sites secure.
Our docs on Managing Domains and DNS have been overhauled to include more information on convenience domains, and domain mapping for VIP Go multisites.
We’ve added some more documentation on using multisite on VIP Go.

WordPress.com documentation has moved to the Lobby

This notice relates to the following platforms: WordPress.com VIP

Our focus moving forward is on making VIP Go the preeminent platform for developer empowerment in the same way that it is for security, scale, flexibility, and performance. As part of that focus and to reduce potential confusion among incoming users, we have moved all documentation relating to our legacy WordPress.com VIP platform from the main site to the Lobby.

As has been the case for over a year now, all new clients are launched on VIP Go. If you have sites hosted on WordPress.com VIP rather than VIP Go, you may not be aware of all of the useful features and enhancements that have rolled out to our main platform in the past twelve months. Here’s a quick rundown of the highlights:

If you’re on WordPress.com, and need to access documentation specific to that platform, you can reach the landing page here.

Documentation for VIP Go will remain at vip.wordpress.com/documentation.

If you’d like to learn more, or you’re interested in moving your site from the WordPress.com VIP platform to VIP Go, please get in touch!

Next Steps with Gutenberg

As of the State of the Word in December(#), WordPress version 5.0 was targeted to ship some time around April 2018. It will have the new Gutenberg editor as one of its leading and most anticipated features. While we have no additional information as to when it will be ready, and April is just around the corner, now is the time to start preparing if you haven’t already. As we have mentioned previously(#), VIP will be deploying 5.0 per our usual procedures, but we will make sure that the Gutenberg editor is defaulted to off initially unless you take further action.

We have been working on a number of fronts to equip you for a smooth transition to WordPress 5.0 and the new Gutenberg editor, and have lots of exciting updates to share! Read on for news about the transition itself and how it will work, tools for experimentation and testing, and VIP-exclusive Gutenberg learning materials on the way.

1. Gutenberg transition tool

Everyone’s transition plan will look a little different. We’re readying a plugin that will allow you to decide when the new editor surfaces in your workflow, on the Post and Page type level, from not at all to all-in and anything in between. You’ll be able to do this well ahead of time (soon in fact!) and make changes to it as your transition plans come together. Whatever those settings are when 5.0 deploys will determine how Gutenberg surfaces. Once this plugin is ready to go, we will be enabling it for all VIP’s set to “classic editor only” as default.

This will put you in control of the details, and if you choose to do nothing, the new editor will stay defaulted to “off” for all content types. It will give you the runway to test all of your customizations and integrations ahead of time, and plan a thoughtful and granular transition if that’s what suits you best. If you are ready to rock with Gutenberg throughout your post types and pages right out of the gate, it will be easy to do that too.

Next step for VIPs: Start talking to your teams about how you want to surface the new editor interface, and work on your test plan. We’re here to help if you’d like some guidance.

2. Call for testers

We’d love your help in testing this transition tool. We’re looking for a few clients who are willing to participate in a final beta test before we roll it out to all clients. If you’re interested, send a note to Allison at allison.blanda@automattic.com.

3. Prepare your teams

WordPress VIP is partnering with WordPress pros Joe Casabona and Zac Gordon to help prepare your teams for working with Gutenberg. We will be offering free video education courses to all clients. These will focus on teaching your editorial, product and development teams about the ins-and-outs of the new editor.

4. Press check time

We will be sharing a new testing site shortly that allows you to experiment with Gutenberg as a front-end experience. This will be particularly useful for editors and content creators who want to see what working with blocks is like and who may not have access to a local test environment. More on that very soon!

We also have a new documentation page dedicated to tracking all things related to Gutenberg at VIP. We’ll continue to share updates here as well, but will maintain that page as an ongoing one-stop shop.

Deprecating VIP Quickstart

This notice relates to the following platforms: WordPress.com VIP

As of today, VIP Quickstart is officially deprecated as a development environment for WordPress.com. With Quickstart’s version of Ubuntu (12.04) approaching end-of-life, we’re switching local development for WordPress.com VIP to more closely match our approach on VIP Go.

Going forward, we recommend using Chassis or VVV, with WordPress.com VIP mu-plugins and some extra development plugins. Both of the recommended environments are widely used in the WordPress community and we think the experience is better than we could offer with VIP Quickstart. (You’re also welcome to use a WordPress setup of your choice.)

We have a new documentation page that covers how to set up a development environment for your WordPress.com VIP project.

We no longer recommend setting up new Quickstart environments, though we will continue to provide support through to April 21, 2017.

As always, please reach out if you have any questions or run into issues.

Lean Commits === Swift Deploys

One of the most common actions of a developer working on a WordPress.com VIP-hosted project is committing code through our review workflow. We want to get your code deployed quickly while also making sure it is secure and performant, and this process involves human review. (Read more about why we do code reviews.)

A few months ago, we implemented automated PHP CodeSniffer checks on incoming commits. This allows us to provide some kinds of feedback on your commits right away, speeding up the overall review feedback process. As always, we encourage you to set up PHPCS in your local development environment too.

We also ask you to keep your commits small. Large commits take longer to review, can be more complex and can hold up other commits. If the changeset is larger than about 1,000 lines of code it may need more time than our traditional review/deploy workflow facilitates, to give it the proper attention it deserves. In these cases we may revert the commit and ask you to consider smaller, more atomic commits, or push the changes to a scheduled review and follow up in a support ticket about planning a timeline for that.

When we consider the size of a changeset we’re looking at the pending commits sitting in the queue. For example, if there are 3 commits around 900 lines each all committed fairly close together it’s likely we’ll end up looking at all of these as a single changeset. That would push over the limit and we may need to take a bit longer to perform the review, or review those outside of the review/deploy queue.

There are several ways commits can have a more efficient journey through the queue;

Commits should have less than 1,000 lines of new or modified PHP and unminified JS (aka reviewable code),
Changesets should be logical, atomic and well described (read our docs on creating good changesets),
The commit message should follow our guidelines on writing good commit messages.

Whenever you’re in doubt, please open a ticket with us and check first. We’ll always be happy to help you think about ways to create smaller commits so they have a smooth journey through to deployment.

Happy committing!

Support Documentation Updates

Hello there! This is the newest addition in a series of periodic posts where we will highlight new support documentation and/or any changes made to existing docs. This is a great way to stay up-to-date with the latest VIP coding standards.

New Updates to “Validating, Sanitizing, and Escaping”:

Escape on String Creation
- Addition:
  - It is sometimes not practical to escape late. In a few rare circumstances you cannot pass the output to wp_kses since by definition it would strip the scripts that are being generated.
    In situations like this always escape while creating the string and store the value in a variable that is a postfixed with _escaped, _safe or _clean.
  - So instead of $variable do $variable_escaped or $variable_safe. Functions must always return “safe” html that do not rely on them being late escaped. This allows you to do echo my_custom_script_code(); without needing the script tag to be passed thru a version of WP_KSES that would allow such tags.

rawurlencode() should be used over urlencode() for ensure URLs are correctly encoded. Only legacy systems should use urlencode().
```
&lt;?php echo esc_url( 'http://example.com/a/safe/url?parameter=' . rawurlencode( $stored_class ) ); ?&gt;
```

New Updates to “Quickstart”:

To create unit tests for your plugin/theme
- Removal:
  - Important Note: Due to the PEAR install method being at end-of-life, PHPUnit does not currently install properly on Quickstart, and so unit testing will not work. We’re working on a new install method that addresses this.

New Addition to “Manipulating Changes”:

Manipulating Changes
- We also support the WebP image format—and while WebP isn’t yet supported by all browsers, we auto-detect which browsers your readers are using to make sure they can enjoy your images at the best possible quality. Our system will always serve your viewers the best image format at the highest speed possible.

New Addition to “Caching”:

Example: Caching WP_Query

Try and avoid cache slams when setting multiple caches by using a more random cache expiration time, using something like:

&lt;?php $args = array( 'orderby' =&gt; 'comment_count', 'posts_per_page' =&gt; '1', 'ignore_sticky_posts' =&gt; 1 );
$query = new WP_Query( $args );
while ( $query-&gt;have_posts() ) : $query-&gt;the_post();
	// do stuff
endwhile;

Here’s how to modify that loop to cache the results of the WP_Query object:

// First, let's see if we have the data in the cache already
$query = wp_cache_get( 'ordered_comments_query' ); // the cache key is a unique identifier for this data

if( $query == false ) {
	// Looks like the cache didn't have our data
	// Let's generate the query
	$args = array( 'orderby' =&gt; 'comment_count', 'posts_per_page' =&gt; '1', 'ignore_sticky_posts' =&gt; 1 );
	$query = new WP_Query( $args );

	// Now, let's save the data to the cache
	// In this case, we're telling the cache to expire the data after 300 seconds
	wp_cache_set( 'ordered_comments_query', $query, '', 300 ); // the third parameter is $group, which can be useful if you're looking to group related cached values together
}

// Once we're here, the $query var will be set either from the cache or from manually generating the WP_Query object
while ( $query-&gt;have_posts() ) : $query-&gt;the_post();
	// do stuff
endwhile;

New Additions to “Code Review: What We Look For”:

Use wp_json_encode() over json_encode()
- wp_json_encode() will take care of making sure the string is valid utf-8 while the regular function will return false if it encounters invalid utf-8. It also supports backwards compatibility for versions of PHP that do not accept all the parameters

Use wp_parse_url() instead of parsurl()
- In PHP versions lower than 5.4.7 schemeless and relative urls would not be parsed correctly by parse_url() we therefore recommend that you use wp_parse_url for backwards compatibility

Minified Javascript files
- Javascript files that are minified should also be committed with changes to their unminified counterparts. Minified files cannot be read for review, and are much harder to work with when debugging issues.

Inserting HTML directly into DOM with Javascript
- To avoid XSS, inserting HTML directly into the document should be avoided. Instead, DOM nodes should be programmatically created and appended to the DOM. This means avoiding .html(), .innerHTML(), and other related functions, and instead using .append(), .prepend(), .before(), .after(), and so on. More information.

Use wp_safe_redirect() instead of wp_redirect()
- Using wp_safe_redirect(), along with the allowed_redirect_hosts filter, can help avoid any chances of malicious redirects within code. It’s also important to remember to call exit() after a redirect so that no other unwanted code is executed.

Mobile Detection
- When targeting mobile visitors, jetpack_is_mobile() should be used instead of wp_is_mobile. It is more robust and works better with full page caching.

Using bloginfo() without escaping
- Keeping with the theme of Escaping All the Things, code that uses bloginfo() should use get_bloginfo() instead so that the data can be properly late escaped on output. Since get_bloginfo() can return multiple types of data, and it can be used in multiple places, it may need escaped with many different functions depending on the context:
```
echo '&lt;a href=&quot;' . esc_url( get_bloginfo( 'url' ) ) . '&quot;&gt;' . esc_html( get_bloginfo( 'name' ) ) . '&lt;/a&gt;';

echo '&lt;meta property=&quot;og:description&quot; content=&quot;' . esc_attr( get_bloginfo( 'description' ) ) . '&quot;&gt;';
```
Custom wp_mail headers
- The PHP Mailer is properly escaping headers for you only in case you’re using appropriate filters inside WordPress. Every time you want to create custom headers using user supplied data (eg.: “FROM” header), make sure you’re using filters provided by WordPress for you. See https://developer.wordpress.org/reference/hooks/wp_mail_from/ and https://developer.wordpress.org/reference/hooks/wp_mail_from_name/

Functions that use JOINS, taxonomy relation queries, -cat, -tax queries, subselects or API calls
- category__not_in, tag__not_in, and tax_query with NOT IN (these should never be used unless using Elasticsearch)

reCaptcha for Share by Email
- To protect against abuse of Jetpack’s share by e-mail feature (aka Sharedaddy) it must be implemented along with reCaptcha. This helps protect against the risk of the WordPress.com network being seen as a source of e-mail spam, which would adversely affect VIP sites. This blog post explains how to implement reCaptcha.

Using closing PHP tags
- All PHP files should omit the closing PHP tag to prevent accidental output of whitespace and other characters, which can cause issues such as ‘Headers already sent‘ errors. This is part of the WordPress Coding Standards.

New Update to “Uncached Functions”:

get_posts()
- When using WP_Query instead of get_posts don’t forget about setting ignore_sticky_posts and no_found_rows params appropriately (both are hardcoded inside a get_posts function with value of true )

New Update to “Term queries should consider include_children => false”:

We recommend ’include_children’ => false to be added to all taxonomy queries when possible.

New Update to “Gravatars and Blavatars”:

Disabling
- If you are not using Gravatars and Blavatars and need to disable the loading of related Javascript and CSS resources, you can use wpcom_vip_disable_hovercards() in your theme.
- You’ll also want to disable the default favicon redirect with remove_action( 'init', 'dynamic_favicon' );

New Support Documentation:

That’s about it! If you have any questions, please feel free to open up a support ticket with us!

Category Archives: Doc Updates

Now Available: An easier way to test Jetpack releases

Support Documentation Updates: Q1, 2019

Documentation architecture updates

New and updated documentation

Support Documentation Updates: December edition

New documentation:

Updated documentation:

Support Documentation Updates

New documentation:

Updated documentation:

Other documentation news:

WordPress.com documentation has moved to the Lobby

More Gutenberg Dev How-To Videos

Next Steps with Gutenberg

1. Gutenberg transition tool

2. Call for testers

3. Prepare your teams

4. Press check time

Deprecating VIP Quickstart

Lean Commits === Swift Deploys

Support Documentation Updates