The VIP code analysis bot

VIP Go platform specific

This document is for sites running on VIP Go.

Learn more

Overview #

When you create a Pull Request (PR) on a VIP client site repository in the VIP GitHub organization (https://github.com/wpcomvip/), you may see a review from our automated VIP Code Analysis bot. The bot’s GitHub username is wpcomvip-vipgoci-bot, and you can see their GitHub user account.

↑ Top ↑

What does the bot do? #

The bot runs our PHP_CodeSniffer (PHPCS) ruleset with the WordPress-VIP-Go standards, and also the PHP linter.

The PHP linter will highlight code syntax and compilation errors, these are usually fatal and so need to be addressed before the code is deployed.

PHPCS is a tool that will help you write VIP approved code by ensuring it meets VIP coding standards. The rules are designed to identify where code will not work, and to help you follow VIP best practices for writing secure, performant, and future-friendly code. We recommend you install the PHPCS and the ruleset locally by following the documentation here, and this will give you even more immediate feedback as you develop.

The bot works by adding a GitHub PR review (or reviews) detailing the feedback based on our ruleset. A review with no issues will show no interaction from the bot, whereas if the bot finds either PHPCS or PHP linting errors the bot will comment on and review the PR:

↑ Top ↑

What should I do about the bot feedback? #

You should review the feedback from the bot, and decide how to act on it. You have several choices for each item of feedback:

  • Address the feedback by amending your code
  • Choose to ignore the feedback, and add code comments to instruct the bot to ignore the issue (see below)
  • Dismiss the review issue via the GitHub PR interface

Many issues will be correct and should be addressed, but as with all automated feedback there will be some wrongly flagged issues that it is safe to ignore (false positives). There may also be some issues that the bot feedback misses (false negatives). We aim to reduce false positives and false negatives over time, please feel free to open a ticket if you find such and we’ll be happy to discuss.

If you have any concerns about a review added by this bot, please open a ticket and we’ll be happy to help.

↑ Top ↑

Code comments to ignore PHPCS feedback #

You can configure the bot to ignore certain parts of the when running the PHPCS ruleset as described in “Ignoring Parts of a File” from the PHPCS documentation. Here’s an example:

// Ignore a single line:
$xmlPackage = new XMLPackage; // phpcs:ignore WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase -- reasons

// Disable the a check for multiple lines, and then enable all checks at the end:
// phpcs:disable WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase -- reasons
$xmlPackage['error_code'] = get_default_error_code_value();
$xmlPackage->send();
// phpcs:enable

Read the PHPCS documentation for other methods to have the scanner ignore portions of a file or whole files.

↑ Top ↑

Modifying the bot’s behavior #

You can change the bot’s behavior by placing a configuration file named .vipgoci_options at the root of the relevant repository. This file file must contain a valid JSON string for this to work; if the file is not parsable, it will be ignored. This file is where you can add code to turn off support messages as well as adjust PHPCS severity levels.

↑ Top ↑

Turning support messages off #

By default, the bot will post a support message to new PRs explaining what it does as well as what to expect next. This message can be turned off. (See the example in the next section.)

↑ Top ↑

Adjusting PHPCS Severity #

You can increase or decrease the number of warnings and errors generated by the bot by adjusting its PHPCS severity level.

By default, the bot runs at severity=1.

To turn off support comments and adjust the PHPCS severity level, use the following JSON snippet in your .vipgoci_options file:

{"post-generic-pr-support-comments":false,"phpcs-severity-level":1}

Please note, while you can configure either parameter, you do not need to configure both. We recommend that you only configure the option that you need to configure. We also recommend that you only configure the PHPCS severity level if you understand how to use that PHPCS option and understand the implications of its use.

↑ Top ↑

Skipping PHPCS scanning for specific Pull Requests #

By default the bot will scan any new PRs with PHPCS and PHP Lint. However, in some cases you might not want it to scan the PHP code with PHPCS. To accomplish this, add a label to the relevant PR simply named skip-phpcs-scan without any extra strings or content. Only use this label if you do not want the code to be reviewed by the bot.

↑ Top ↑

Skipping PHPCS scanning for specific folders #

By default the bot will scan any relevant files found in PRs using PHPCS and PHP Lint. For PHPCS, both JavaScript and PHP files are scanned for issues, while for PHP Linting only PHP files are scanned for syntax errors. In some cases this can result in files being scanned that should not, such as unit-tests with deliberative syntax errors.

You can add files to the root of the repository indicating folders that should not be scanned. For PHPCS, the file should be named .vipgoci_phpcs_skip_folders. For PHP Linting the file should be named .vipgoci_lint_skip_folders. Please ensure both files are located in the root of the repository.

List each folder to be skipped on individual lines within those files. For example, to skip PHP Linting, you would list folders in the file named .vipgoci_lint_skip_folders like so:

themes/news-site-theme/unit-tests
plugins/third-party-plugin-v2

With these two paths in the .vipgoci_lint_skip_folders file, no PHP files in those folders will be checked for syntax errors. The usage is analogous with PHPCS. Note that regular expressions are not supported at this time.

We encourage you to use this feature sparingly. We view the checks as a safety mechanism that can save your sites from serious errors.

↑ Top ↑

GitHub API communication error #

Occasionally the bot will post a message to PRs saying that there has been a GitHub API communication error and that a human should be contacted. This happens when the bot has a problem communicating with the GitHub API, and in most cases this is due to problems with the GitHub API itself. The message usually disappears when the PR is scanned again, which occurs when new commits are pushed to the PR.

If the problem persists, first check if there are any issues with the GitHub API (see here). If all systems appear operational, and the problem persists, please open a support ticket with us and we will investigate.

Ready to get started?

Drop us a note.

No matter where you are in the planning process, we’re happy to help, and we’re actual humans here on the other side of the form. 👋 We’re here to discuss your challenges and plans, evaluate your existing resources or a potential partner, or even make some initial recommendations. And, of course, we’re here to help any time you’re in the market for some robust WordPress awesomeness.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.