Help Test PRs to Accelerate the Revolution 3.0 Release

By Ryan Thrash
August 28, 2020
Help Test PRs to Accelerate the Revolution 3.0 Release

MODX 3 is nearing feature freeze ahead of its beta cycle and subsequent release. Because we need as much help as possible testing and validating key issues and Pull Requests (“PRs”), we created this tutorial on an approach for those who may not be used to living in the command line and working with git every day.

Currently, there are about a dozen PRs that should be merged before the final alpha release.

During alpha, things that break backward compatibility are candidates for inclusion in the 3.0 release. During the soon-to-follow beta releases, however, no more breaking changes will be accepted. Beta is intended for polishing things up and working towards making sure as many Extras as possible will work without refactoring. Many already do.

Who this Tutorial is For

You don’t have to be a core developer to review PRs, but you should probably know your way around the MODX Manager.

You can check that things still work and review proposed design changes. Really, the only requirement is being able to execute a few things on the command line/shell, which can be mostly copy/pasted from below.

On Macs, this is typically via 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 sign up today if you aren’t already a member and want to get involved.

The more people that add feedback, especially the PRs already slated for the next release, the better. It will speed up the ultimate release of 3.0 which we are focusing on for later this year.

How to get involved

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

  1. Install Revo 3.0 from Git
  2. Check out the PR for testing
  3. Test the changes made in the PR
  4. Provide feedback at Github
  5. Rinse and repeat!

Environment

For a server, you can work locally using something like MAMP. For this tutorial, I used a Flex Cloud instance in MODX Cloud, which also makes it easier to share with people as needed.

The following steps should only take roughly 5 minutes to perform.

1. Install MODX Revolution from Git

First, create a Flex Cloud instance, To make things simpler, I used the Cloud dashboard at the bottom of the Webserver tab to make it the public web root directory:

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

Now, connect to this instance via SSH (though we recommend doing so via SSH keypairs) and cd www to get into the main directory for the webserver.

The TL;DR version that follows will have you quickly executing shell commands to get Revo 3 built and installed from Git, mostly via copy/paste, or you can learn the full details of installing Revo from Git in the MODX Docs.

Once you’ve connected to the server via SSH and have switched to www/, execute the following commands. First, clone the Revo Git repository (“repo”) into the www/ directory:

git clone http://github.com/modxcms/revolution.git

Next, check out the 3.x branch into the now-created revolution/ directory:

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

Set up the instructions for telling it how to build Revo:

cp _build/build.config.sample.php _build/build.config.php
nano _build/build.config.php

At this point you are in a nano session editing the build config file. I changed the bolded parts below with the relevant information from the Cloud Dashboard (example data … use your actual values from the Dashboard):

define('XPDO_DSN', 'mysql:host=127.0.0.1;dbname=instance_c9000_flex;charset=utf8'); define('XPDO_DB_USER', 'c9000'); define('XPDO_DB_PASS', 'bs63yrwdvkn3ez1');

After pressing ctrl-x to exit, and saving the changes, back to the build steps:

cp _build/build.properties.sample.php _build/build.properties.php
nano _build/build.properties.php

Similarly, I made the following changes to the build.properties.php file, saved them and exited using nano:

/* mysql */ $properties['mysql_string_dsn_test']= 'mysql:host=127.0.0.1;dbname=instance_c9000_flex;charset=utf8'; $properties['mysql_string_dsn_nodb']= 'mysql:host=127.0.0.1;charset=utf8'; $properties['mysql_string_dsn_error']= 'mysql:host=nonesuchhost;dbname=nonesuchdb'; $properties['mysql_string_username']= 'c9000'; $properties['mysql_string_password']= 'bs63yrwdvkn3ez1';

One of the great things about MODX Revolution 3 is that it takes advantage of the Composer PHP ecosystem. So we’ll start with installing Composer safely, including a security hash validation and removing the installer when completed.

Start by going back to the main www/ directory:

cd ..
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === 'e5325b19b381bfd88ce90a5ddb7823406b2a38cff6bb704b0acc289a09c8128d4a8ce2bbafcd1fcbdc38666422fe2806') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
php composer-setup.php
php -r "unlink('composer-setup.php');"

Next, we perform a Composer install into our soon-to-be running Revo instance:

cd revolution
php ../composer.phar install

Build the core/ .zip file to prepare for the actual Revo installation to ensure you have all the latest information. Don’t worry if you’re skimming this, most everything above is copy/paste-able, and only takes a few minutes.

cd _build
php transport.core.php

While we’re at it, let’s lock down the core/ directory to avoid the 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 ^~ /core/ {
    deny all;
    return 403;
}

And (finally!), we actually install Revo by opening a web browser and visiting the setup/ directory of our MODX Cloud instance: https​://c9000.paas4.sng.modxcloud.com/setup/ (using the actual address for your Cloud instance).

Follow the six 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.

As such it’s important to not delete the setup directory in the last step of the installation wizard by unchecking the option.

When you’re done, add characters to the install directory name, or exclude it from being web accessible like we did with the core directory above, which you would revert if you need to re-run it again in the future.

2. Check out a PR for Testing

I’m picking a UX-related PR to start with for this tutorial. To get this into your testing instance we need to configure Git to use the PRs as the Git origin instead of the main codebase branch to pull from. We’ll modify the .git/config file inside the repo checked out above with the changed parts in bold, below, on the last line under the [remote “origin”] section:

nano ~/www/revolution/.git/config

This opens the nano editor to update the contents of the file, changing it as indicated in the highlighted locations below:

[core] repositoryformatversion = 0 filemode = true bare = false logallrefupdates = true [remote "origin"] url = http://github.com/modxcms/revolution.git fetch = +refs/pull/*/head:refs/remotes/origin/pr/* [branch "2.x"] remote = origin merge = refs/heads/2.x [branch "3.x"] remote = origin merge = refs/heads/3.x

Save your changes and make sure you’re in the revolution/ directory when you exit nano to pull down the PRs locally:

git fetch origin

This will pull down all the Revo PRs to your local environment and take a minute or so. Finally, we’ll check out the chosen PR to test. We’ll use a single command for this in the format of git checkout origin/pr/PR_ID.

git checkout origin/pr/15149

3. Test. All the Things!

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.

5. Rinse and Repeat

How do you go back to the “clean” version so you can do this all over again, or do you need to do something else? Can you chain multiple checked out PRs?

If your feedback results in a revision to a PR, to get that pulled down locally for further review, simply make sure you’re in your revolution/ directory:

git pull

To get back to the “clean” latest git repo, you re-check it out:

git checkout 3.x && git pull

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

git fetch origin && git checkout origin/pr/123456 

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. If you have something else you'd like to see, let me know.

Start Reviewing MODX Revolution Pull Requests

P.S.
Want to play in MODX Cloud to test and review PRs? Let us know, below, and we’ll sort it out.