Proposal: GitHub Theme Review

As you all know, theme review is one of the things we at the Theme Review Team are doing a lot. We are doing other things, but taking care of the themes repository and checking the quality of themes at wordpress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ has been what this team has been doing for a long long time.

And through this long time period, we noticed several things:

  1. People donā€™t like to read requirements or handbooks šŸ™
  2. Some of the issues that are popping up are repetitive and could be caught automatically
  3. Reviewing themes in tracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. is really cumbersome

This post is not about the first two things. We are constantly discussing about those on the meetings and in the slack channel.

What I want to discuss, and what the representatives have had a discussion on is the third point. Trac. For those of you who donā€™t know what trac is, itā€™s an issue tracking system for software development projects. Itā€™s what the entire WordPress ecosystem uses for handling issues and getting features and bugfixes solved. And itā€™s been doing this job very well for the past 15 years.

However itā€™s not perfect. Especially when it comes to code review and theme review. Looking at code changes is difficult, integrating with trac and the wordpress.org is also tricky and limited, and all in all is not the perfect fit for themes.

Is there a solution for this issue?

In order to try to find the solution to this problem, Iā€™ve had an idea to try to use GitHubGitHub GitHub is a website that offers online implementation of git repositories that can can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ā€˜pull requestā€™ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ for code review. Itā€™s a platform that Iā€™ve been doing all my professional reviews on for the past 4 years. Itā€™s also a platform that many open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. projects are built on.

Even coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. started using GitHub for development more and more (it still uses SVNSVN Apache Subversion (often abbreviated SVN, after its command name svn) is a software versioning and revision control system. Software developers use Subversion to maintain current and historical versions of files such as source code, web pages, and documentation. Its goal is to be a mostly compatible successor to the widely used Concurrent Versions System (CVS). WordPress core and the wordpress.org released code are all centrally managed through SVN. https://subversion.apache.org/. under the hood), and you can also link your wordpress.org account with that on GitHub.

With the pull request review style of reviewing you have a better overview of the code changes, you can check only the changes from the last commit (which also speeds up code review a ton), you can utilize Travis CI to run some automated checks on your code, and you can use GitHub actions to do some tasks when things get approved.

The tagging system is better and clearer, multiple reviewers can review a theme, you can comment directly on the offending line so that the author can see the issue more clearly (and you can leave a suggestion of how to fix the issue). Itā€™s an overall better fit for theme reviews.

Proposed GitHub review flow

So how would this review flow look like? Something like this

Flow diagram of proposed WordPress Theme review on GitHub

You can right click on the image and open it in the new tab to see it enlarged.

The process would still involve trac, as this is something that is working and is ingrained in how themes are added to the repository. The first step wouldnā€™t change. Youā€™d upload a zip file of your theme, as you do now. The theme is checked using theme-check pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party, a corresponding trac ticket is created.

There will be a repository on GitHub called (this is still not implemented of course) theme-reviews. Letā€™s say your theme name is uploaded and a trac ticket 12345 - Cool Theme is created. Once the theme is uploaded two branches would be created in the repository out of the master branch: 12345-Cool-Theme and approved-12345-Cool-Theme. A pull request would be created from 12345-Cool-Theme towards the approved-12345-Cool-Theme (both are branched out from master, but the code from the zip file would be added to the 12345-Cool-Theme branch).

The pull request would trigger a Travis CI process where we could run some automated checks like PHPCS checks with WPThemeReview coding standards, StyleLint checks for css or scss files and ESLint for JavaScript code.

These checks could be set to either output info or warnings (we currently have a lot of false positives on some PHPCS checks so we cannot just use those as is), and they could be used as a way to inform authors about potential issues in their themes.

Authors should fork the repo to their repositories and work on their theme branch, so that they can update the code as the review progresses.

Once all the issues are fixed, and the theme is reviewed, a pull request would be merged in the approved-12345-Cool-Theme branch and a GitHub action would be triggered that would tag this as a new version, upload it to Trac and then the theme could be set live. The theme branches would be deleted to keep the repository clean enough.

The above is a proposal of a potential workflow that could help reviewers review code. Organisation in GitHub can have different teams set, and users could be added as reviewers, trusted reviewers and admins. Every group can have certain privileges (approving, merging a PR etc.).

So whatā€™s next?

What is needed now is to dissect this idea ā€“ see what steps are needed to happen from a technical standpoint and if this is doable.

We do depend on systems (metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. team) help with this one, to see if and how difficult or easy it would be to create branches from the servers that are handling the theme uploads. We need to see what can be done with GitHub actions (we know that there already is a lot that can be done with them ā€“ 10up GitHub plugin actions).

We also need advice to see if we missed some steps, and what could be improved.

Ultimately, we want to improve the review experience. GitHub has proven as a great tool to do code reviews ā€“ the UIUI UI is an acronym for User Interface - the layout of the page the user interacts with. Think ā€˜how are they doing thatā€™ and less about what they are doing. is better than trac and the UXUX UX is an acronym for User Experience - the way the user uses the UI. Think ā€˜what they are doingā€™ and less about how they do it. is better, and we can utilise some automatic tools to speed up the reviews. Plus with the core using GitHub more and more (especially with the core editor), itā€™s about time for the theme review to utilise this great tool in order to improve the reviews and potentially shorten the author wait time.

#github, #review, #theme-review-team