A great way to get involved with Open Source software is by testing and offering feedback on Pull Requests ("PRs"), the subject of this tutorial.
Who this Tutorial is For
You don't have to be a developer to review PRs, but you should know your way around the MODX Manager and probably know how to use the browser console and/or how to look at Manager error log and the PHP error log. The more people providing feedback, the better, helping speed up future releases.
You also need an account on Github.com, so create one today if you haven't already—your geek-cred will go up by at least 10x.
The following steps outline how 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 (CLI), all of which is mostly copy/paste. On Macs, this usually means Terminal.app, on Windows, Putty, and on Linux … well if you're on Linux you already know.
How to Get Involved
To provide feedback when reviewing PRs you'll do the following things:
- Install MODX Revolution using Composer
- Check out PRs for testing using Git CLI tool
- Build if needed (sometimes, often not required)
- Test the changes made in the PR
- Provide feedback at Github
- Rinse and repeat!
Set Up a Testing Environment
For this tutorial, I used a Flex Cloud instance in MODX Cloud. 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):
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 Manager warning about it being web-accessible in the Dashboard:
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
sh -c "$(curl https://modx.co/scripts/install.sh)"
exit
You have to logout and log back in via SSH to continue. This allows the changes to the just installed software to be globally available at the CLI, 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).
You will need to define the git SSL certificate locations. This is essential as otherwise the next step will not work correctly.
git config --global http.sslCAinfo /etc/ssl/certs/ca-certificates.crt
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_NO_DEV=0 composer create-project --keep-vcs modx/revolution 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://af2drib94.modx.dev/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/revolution/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:
cd ~/www/revolution
git checkout 3.x
git status
2. Install the Github CLI Tool
The Github CLI tool makes checking out PRs and working with the code a much easier process. For MODX Cloud, you want the
linux_amd64 version. This article should always have the latest version of the client which should be:
2.92.0. To confirm, in a web browser, visit
https://github.com/cli/cli/releases/latest to see
latest release.
cd ~/www
curl -JLO https://github.com/cli/cli/releases/download/v2.92.0/gh_2.92.0_linux_amd64.tar.gz
tar zxvf gh_2.92.0_linux_amd64.tar.gz
mv gh_2.92.0_linux_amd64/bin/gh ~/.bin
rm gh_2.92.0_linux_amd64.tar.gz
rm -rf gh_2.92.0_linux_amd64
The commands above downloads the latest release, uncompresses it, then moves the binary so it's available everywhere from the 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. Build if Required
Some PRs require a build before you can test them. A build is how MODX processes dependencies, compiles assets, and packages the core for installation. When a PR changes the database schema, modifies JavaScript or Sass files, or updates PHP dependencies, you'll need to run a build.
The PR description or comments will usually indicate if a build is needed. If you're unsure, check what files were
changed. Changes to files in _build/templates/default/sass/, core JavaScript files in manager/assets/, or the
database schema typically require a build.
Building the Core
Building the core creates the transport package (core/packages/core.transport.zip) used during installation. You'll
need to do this when a PR affects the database or installation process.
Before your first build, copy the sample config files:
cd ~/www/revolution/_build
cp build.config.sample.php build.config.php
cp build.properties.sample.php build.properties.php
You don't need to modify these files. Run the build script:
cd ~/www/revolution
php _build/transport.core.php
This takes 5-30 seconds. After the build completes, run setup again via your browser (e.g.,
https://yourinstance.modx.dev/setup/). If you removed the setup directory after initial installation, you'll need to
remove the ~/www/revolution/setup/.locked/ directory first.
Building Assets
Building assets compiles Sass to CSS and processes JavaScript for the Manager interface. You'll need Node.js installed.
The build workflow is located in _build/templates/default/.
Navigate to the build directory and install dependencies:
cd ~/www/revolution/_build/templates/default
npm install
Run the build:
npm run build
For detailed asset build instructions, see the README in the build directory or the MODX documentation on building assets.
When in Doubt
If you're not sure whether a build is needed, check the PR comments or ask. The worst that happens if you skip a needed build is that your tests won't reflect the actual changes.
4. Test. All the Things!
I picked a UX-related PR to start with for this tutorial, but you'll want to choose one from the current PR list where marked Review Required. 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?
5. 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.
6. 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 switch back to the "clean" latest 3.x dev branch repo:
git checkout 3.x && git pull
That's it. You're now able to help review PRs. We'd love to see you involved reviewing the open MODX Revolution pull requests that are marked Review Required. 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
About Ryan Thrash
Ryan Thrash co-founded MODX in 2004 and has served as CEO since 2010. He has worked in open source web software for more than 20 years, leading the development of MODX Revolution and later launching MODX Cloud. He lives in Dallas, TX, with his family and Fred the mini Golden Doodle.
Learn more about Ryan Thrash.