Agenda for June 27

This weeks meeting is estimated to take longer than our usual 30 minutes since we have several topics.

Meeting times and agendas

  • Since we don’t have agendas each week and because people are not able to participate every week, the suggestion is to have two meetings a month: one with a set agenda, and one with an open floor.
  • The meetings are estimated to be one hour long, compared to the 30 minutes we have now.
  • We will try to document topics that come up often, maybe on the FAQ page or a dedicated meeting topics page.
  • If you want to lead a meeting please DM one of the Team Leads which dates you are available.
  • The two weeks per month when we don’t have meetings should be dedicated to working on our ongoing projects.
  • We would like to remind everyone to please stick to the topics so that we can have productive meetings.

Shindigs

Our next review shindig is on saturday july 8.

Two themes rule

We suggest allowing authors to have two themes in the queue, up from one. This should then be evaluated after one month.

WordCamp Europe, community summit and contributor day recap

  • New reviewer tool -Trac will be replaced
  • Readme file will be parsed
  • No more queue
  • Reviewers will not be assigned to tickets
  • Tickets will not be closed just because there is no reply within 7 days
  • Tickets will not be closed because of code errors
  • Updates via SVN

Discussion: What can we do now/short term?

Comparison between the Theme and Plugin review process

  • As we are discussing how we can improve the Theme Review process it would be good to see how our process compares to the Plugin Review process. It would help both teams to align so that we could both profit from improvements made to either system. Both processes are always changing. Parts of the process today may change tomorrow. The plugin review team is working on making the plugin review process public so that others can contribute.
Review Process Themes Plugins
Submission zip file  zip file
Review management in trac (Public) in the WordPress admin area (Private)
Review updates  via trac via email
Reviewers Anyone with a w.org account select group of experienced reviewers (will change in the future but only experienced reviewers will communicate with the developers)
Number of reviewers varied between 10 – 30 active reviewers 5-6 reviewers
Experience level of reviewers variable highly experienced
Reviewer training regular  not needed
Order of reviews order of submission  order of complexity of the plugin
Volunteer time minimal sponsored time sufficient time sponsored
Approval A final review is done by an experienced reviewer before going live The review approves the theme and then the developer must commit the code to SVN
Theme Updates Via zip files via SVN
Theme update reviews only automated reviews no additional reviews
Feedback on the review process Anyone can give feedback and work to improve the review process The small group of reviewers make the decisions
Automated Testing checking for common issues simple testing for PHP errors
Requirements A single detailed document of all of the requirements. Multiple pages on the guidelines: The general guidelines, a reviewer’s checklist and a page explaining how to check for these items.

My learnings from this have been:

  • A small highly experienced team with the resources can sometimes been more effective than a larger team.
  • Having separate information for developers and reviewers may change the public perception of the number of requirements.
  • As the plugin and theme reviewers are looking for similar issues it may be better to work together to unify some of the documentation.

Restructuring the Theme Review Team

At the meeting on Friday with Matt, it was suggested that we should have Team Reps who could make the final decision as a direct democracy does not really work well in our situation. A few reason for this is the number of people active in a team meeting and voting on the same issue in another place and time may give different results.

The suggested restructure of the theme review team would be:

Team Reps/Team Leads

  • These people would be people who are experienced with theme reviews and willing to give their time to leading the Theme Review Team forward.
  • Responsibilities would include
    • Leading the team forward
    • Listening to the team opinions and making a decision
    • Communicate with other Teams and Team Leads
    • Help moderators with their tasks

Moderators

  • These would be people who are experienced members of the theme review team who help out with different administrative tasks.
  • These tasks could involve:
    • Doing final reviews and setting themes live
    • Returning tickets to the queue that have been abandoned
    • Assigning Trainee Reviewers themes
    • Giving a second opinion in tickets
    • Maintaining the requirements documentation
    • Leading team meetings
    • Writing the agenda
    • Fixing issues with themes not going live
    • Removing themes from the repo
  • Depending on what administratives tasks are done access will be provided.
  • All current Key Reviewers and Trusted Reviewers will become moderators.

Reviewers

  • There is no real change here. They can assign themselves reviews.
  • Are able to lead and work on projects and bring ideas of ways to improve.

Trainee Reviewers

  • This is everyone else who can assign themselves a ticket via the assign ticket button.
  • Are able to lead and work on projects and bring ideas of ways to improve.

Details on the new theme settings (customizer) guideline

During yesterday’s team meeting, we made what we knew would be a controversial decision about theme settings. This post will go into more details about this decision and how we plan to move forward.

Continue reading

Why are we working to improve the automation of the theme review?

During the last few years, the WordPress Theme Review Team has had a hard time to keep up with the volume of submitted new themes.

A high number of submissions is a good problem to have. But it means that developers have to wait a long time before their theme is published.

A theme review includes a lot of routine tasks. Examples are checking for the use of deprecated functions, or lack of support for core WordPress features. A lot of these tasks do not need the intervention of a human reviewer, and could be made by software.

The benefits of automation

The Theme Check plugin was created in 2011, and is used to scan every theme uploaded to WordPress.org. It runs checks on the submitted theme, and blocks themes that fail checks for required items.

The number of checks, and the issues detected by the checks have been improved over the years. But not all the requirements in the review guidelines are verified by the plugin. This leaves the task of verifying these requirements to the reviewers.

In June 2016, the admins started a project to improve the automation of theme review tasks. The goal of this project is to automate as many routine tasks as possible.

This automation has the following benefits:

  • By detecting more required items during the upload process, themes that fail elementary guidelines will not make it into the review queue. This will reduce the number of theme review tickets that get closed after a quick review due to fundamental flaws in the theme code.
  • By using better analysis tools, the number of issues missed by a reviewer will diminish. Some themes have large code bases, making it difficult to catch all issues. This is important in the context of security, as one flaw is often all that is needed to put an entire install at risk.
  • By using the new tool during the scans of automated theme updates, the quality of the themes will be kept at a high level.
  • By having software handle the menial work, reviewers can focus on areas where their expertise is needed, and provide a real benefit to theme authors.

The flaws of the Theme Check plugin

The Theme Check plugin has a fundamental flaw, and that is the reliance on text parsing for detecting errors.

A text parser only understands text. It has no notion of what valid PHP code is, and what isn’t. This can mean that a check will pass, although the theme does not respect the guideline. A tool on which the reviewer cannot rely is a lot less useful, since double checking is needed.

Additionally text parsing relies on regular expressions, which are difficult to write. This can lead to bugs, which in the worst case can block a valid theme from being uploaded. This leads to lack of trust in the tool by developers, who see it as a nuisance, rather than a useful tool.

The unreliability, coupled with the absence of unit tests, make the Theme Check plugin difficult to maintain. The risk of unintentionally introducing regressions is too high.

There have been attempts to use the PHP tokeniser API in checks to avoid text parsing. This API is a set of functions that provide an interface into the PHP tokeniser in the Zend Engine, which is the standard PHP interpreter.

A tokeniser breaks text up into elements called tokens, which get passed to a lexer, that attaches meaning to the tokens. This means that after this operation, you can determine what a token represents, based on its internal type as used by the PHP interpreter.

The problem with the current use of the PHP tokeniser in checks is that the API is too low level to be useful. Additionally transforming source code to tokens is an expensive, and therefore a slow operation.

The current architecture of the Theme Check plugin does not offer a high level API to use the tokeniser in checks in a performant way. It needs to be rewritten from scratch, using better tools. After a discussion at WordCamp Europe between the theme review admins and other developers, using PHP_CodeSniffer seemed to be the best solution.

A better approach, the PHP CodeSniffer

PHP_CodeSniffer (PHPCS) is a static code analysis tool, meaning that it can analyse code without running it. PHPCS tokenises code, and runs sniffs on them. These sniffs serve to detect violations of a defined coding standard.

PHPCS has coding standards for all major PHP projects, and WordPress is one of them, with a standard called WPCS.

Using WPCS has four major advantages:

  1. The existing sniffs for the different WordPress coding standards give us a head start on detecting essential issues.
  2. PHPCS has offers a higher level API for interacting with the PHP tokeniser, making sniffs easier to write.
  3. With the WPTRT participating in the development of WPCS, there will be more contributors to the project. This tool is a crucial tool for the WordPress ecosystem. More developers means a bigger positive impact on WordPress as a whole.
  4. WPCS can be integrated with most editors, and integrated development environments (IDEs). PHPStorm is an example of an IDE with great support for PHPCS checks. This allows the tool to provide feedback while the developer writes code.

The idea is to add a extra coding standard, WordPress-Theme, to the WPCS project. A list of sniffs that would need to be implemented as part of this project can be found on Github.

As part of this project, @jrf has done a great job working on the base WPCS project. The long list of improvements in version 0.10.0 speaks for itself.

Limits of PHP_Codesniffer

The theme review guidelines can broadly be divided into two categories:

  1. Guidelines that cover technical aspects of theme development. An example would be lack of using the `eval()` function. PHPCS is great for detecting issues like this.
  2. Policy guidelines that are specific to a theme distributed on WordPress.org. An example would be a theme tagged with rtl that nonetheless lacks support for RTL languages. PHPCS is unfortunately not the right tool to detect these issues.

This is due to the way that PHPCS works. The sniff process goes through the files one at a time, and runs all the sniffs on the current file. Once all files are processed, the sniff is considered complete. As such the tool has no knowledge of what the object of the sniff is. It just deals with files.

Additionally, PHPCS sniffs detect errors by looking for certain combinations of tokens. So it’s up to the person writing the sniff to know which token pattern represents a function call for example.

To effectively check the policy guidelines, we would need a tool specifically designed for the task. A theme is a collection of PHP, JavaScript, and CSS files, but we would need a tool that goes beyond this basic level.

There is an existing PR on the WordPress-Theme standards repository, that extracts a set of data points from a theme. While the implementation itself is not a final solution, the approach has merit. Rather than dealing with individual files, the relevant information is extracted, and serves as an abstract representation of the theme.

We are currently working on a test project that uses a PHP Parser to extract this information. A parser is one level above a lexer, as it turns the tokens into an abstract syntax tree. This is an advantage, because a parser knows how the tokens fit together.

The library used is in this project is phpDocumentor/Reflection. This library was recommended by @rmccue, since the PHPDoc parser powering the WordPress Code Reference is based on it.

The project is still in an early phase. It will be made available for contributions and testing as soon as a first stable version exists.

How can you help?

If you are a theme developer, start using the WordPress-Theme coding standard as part of your development process.

The WPCS project in general, and the WordPress-Theme coding standard in particular, could benefit from the help of proficient developers.

If you want to follow the advancement of the project, you can attend the automation meetings.

As the guidelines are reviewed and adjusted regularly, make sure to attend the WPTRT meetings.

#review-automation