Updated: Help Test PRs to Accelerate the Revolution 3.0 Release

By Ryan Thrash  |  Updated: November 19, 2021  |  8 min read
Updated: Help Test PRs to Accelerate the Revolution 3.0 Release

MODX 3 is nearing feature freeze ahead of its beta cycle and subsequent release. We need as much help as possible testing Pull Requests (“PRs”) so we updated and simplified this tutorial make it easier to help.

MODX tracks its software releases in Github. The project boards are intended to help people that don’t work on the software daily to see what’s been done, know what’s left to do, and most importantly for this article, the state of PRs: the ones in the “Code Review” column are where the most help is needed, closely followed by PRs to address Issues in the Backlog column.

Who this Tutorial is For

You don’t have to be a core developer or team member to review PRs, but you should know your way around the MODX Manager. The more people providing feedback, the better, helping speed up the 3.0 release.

This tutorial is designed for people that want to review PRs and pre-release software from Git. If you’re interested in actually submitting PRs to implement features or fix bugs, we’ll have a follow-up article for that later.

You can follow the steps below to help check that things still work and review proposed design changes. All it takes is the confidence to execute a few things on the command line/shell/CLI, all of which can be mostly copy/pasted. On Macs, this usually means Terminal.app, on Windows, Putty, and on Linux … well if you’re on Linux you already know.

You also need an account on Github.com, so create one today if you haven’t already—your geek-cred will go up by a factor of at least 10.

How to Get Involved

To provide feedback when reviewing PRs you’ll do the following things:

  1. Install the Revo 3.0 dev code using Composer
  2. Check out PRs for testing using Git CLI tool
  3. Test the changes made in the PR
  4. Provide feedback at Github
  5. Rinse and repeat!

Set Up a Testing Environment

For this tutorial, I used a Flex Cloud instance in MODX Cloud. If you want to help but don’t want to configure a local test environment, we offer free MODX Cloud contributor accounts that make it easy to follow these steps exactly. Request one by filling out the form at the bottom of this page. For local testing, you can use something like MAMP.

The following steps should take less than 5 minutes to perform.

1. Install MODX Revolution as a Composer Project

The TL;DR version that follows will have you execute a series shell commands to install the Revo 3 dev branch as a Composer project in a Flex Cloud instance. You can alternately learn the full details of installing Revo from Git in the MODX Docs.

First, create a Flex Cloud instance. To make things simpler, use the Cloud dashboard at the bottom of the Webserver tab to make www/revolution/ the public web root directory (this will be created later when you install MODX as a Composer Project):

Custom Web Root in MODX Cloud The web root configuration in MODX Cloud

While we’re in the Dashboard, let’s keep people from snooping around the core/ directory (and others) to avoid the annoying eventual and annoying Manager warning about it being web-accessible in the Dashboard:

Update the web rules to block web access of the core directory The web rules configuration in MODX Cloud

Above the default location block, as shown in the screenshot above, add the following:

location ~ ^/(\.(?!well_known)|_build|core|config.core.php) {
    rewrite ^/(\.(?!well_known)|_build|core|config.core.php) /index.php?q=doesnotexist;    

Now, connect to this instance via SSH—we strongly recommend doing so via SSH keypairs—and execute the following commands to install Composer using the handy MODX CLI toolkit, then disconnect from SSH:

cd www
curl http://modx.co/scripts/install.sh | sh

You have to logout and log back in via SSH to continue. This allows the changes to the just installed software to be globally availalbe at the command line, including being able to use Composer anywhere. Connect again to the server (use the up-arrow key to reload your last command in your shell history).

Next, use Composer to install the 3.x branch into a revolution/ directory. This does a lot of things automagically for you like downloading the code and building and configuring the core. When asked if you want to delete the git history, enter n (for no):

cd ~/www
composer create-project --keep-vcs modx/revolution . 3.x-dev

And (finally!), install Revo by opening a web browser and visiting the setup/ directory of your instance using its MODX Cloud URL such as https://c9000.paas4.sng.modxcloud.com/setup/.

Follow the prompts in the install wizard and plug in the details from your MODX Cloud Dashboard. Important note: some PRs may require re-running setup, e.g., when a PR affects things stored in the database, so pay attention to the notes on the PR in Github and make sure to not remove the setup directory on the last step. If you need to run setup again for certain PRs, you will need to ssh back to your instance and delete the www/setup/.locked/ directory in order to do so.

One last thing to do is to make sure Git has a 3.x branch after the Composer create command, but only after you install Revo itself:

git checkout -b 3.x origin/3.x

2. Install the Github CLI Tool

The Github CLI tool makes checking out PRs and working with the code a much easier process. In a web browser, visit https://github.com/cli/cli/releases/latest to see latest release. For MODX Cloud, you want the linux_amd64 version. At the time of this article was version 1.8.1. Modify the commands below to match the latest version as appropriate:

cd ~/www
curl -JLO https://github.com/cli/cli/releases/download/v1.8.1/gh_1.8.1_linux_amd64.tar.gz
tar zxvf gh_1.8.1_linux_amd64.tar.gz
mv gh_1.8.1_linux_amd64/bin/gh ~/.bin

The commands above downloads the latest release (as of the time this article was last updated), uncompresses it, then moves the binary so it’s available everywhere from the command line (CLI).

Before you can work with the gh command, you first have to authenticate:

gh auth login -w

This will allow you to authenticate via a web browser. I had to manually open the authentication page in my browser because remote servers shouldn’t open local browsers. The session:

/paas/cXXXX/www/ $ gh auth login -w
! First copy your one-time code: E980-9Z36
- Press Enter to open github.com in your browser... 
! Failed opening a web browser at https://github.com/login/device
  exec: "xdg-open,x-www-browser,www-browser,wslview": executable file not found in $PATH
  Please try entering the URL in your browser manually
✓ Authentication complete. Press Enter to continue...
✓ Logged in as rthrash

You can now successfully work with PRs in Cloud using gh cli. Note: the authentication does persist across sessions, so you should only have to do that one time.

3. Test. All the Things!

I picked a UX-related PR to start with for this tutorial, but you’ll want to choose one in the Code Review column on the current project board. We’ll use the just-installed gh CLI tool to pull down the relevant PR for testing.

gh pr checkout 15149

Now the real fun begins. In general, you poke and prod to make sure everything matches what the PR author says, and to make sure there aren’t errors.

  • Does it work or do what it says it does?
  • Are there visual errors or inconsistencies?
  • Are there any errors created in the MODX Manager Error Log?
  • Are there any errors in the JS Console of the web inspector?

4. Provide Feedback on Github

Visit the MODX Revolution Github page and find the PR you checked out. In this example, it’s located a https://github.com/modxcms/revolution/pull/15149.

Since everything looked good, I entered a comment to indicate I reviewed the PR in a local install, that it worked as described, and suggested some additional refinements for consideration. I didn’t find any functional errors or JS console errors.

At the time of this article update, our guidelines requires two reviews before a PR can be merged—comments from outside contributors about suggested PR changes can really speed things up. For formal reviews, you need to be on the official contributor team with a Triage role. We’d love to have more contributors so submit a few informal reviews and reach out to us if you’re interested in joining the team. We’ll review your reviews (how meta!) and bring it up to the current integrators and project leaders for a decision.

5. Rinse and Repeat

If you want to review another PR (where 123456 is the ID of the desired PR):

gh pr checkout 123456 

If your feedback results in a revised PR and you still have the PR checked out, you pull the update for further review. Make sure you’re in your revolution/ directory and:

git pull

To get back to the “clean” latest 3.x dev branch repo, you re-check it out:

git checkout 3.x && git pull

That’s it. You’re now able to help review PRs. We’d love to see you involved in the Open Revo pull requests at Github needing review. Up next, I plan on writing how to submit a PR using a fork of the Revo project (which is really easy!). If you have something else you’d like to see, let me know.

Start Reviewing MODX Revolution Pull Requests

Want a free MODX Cloud account to test and review PRs? Let us know, below, and we’ll get you set up.

Get the MODX Insider Newsletter