Here are some notes on participating in MODx Revolution testing and/or development. Unlike previous versions of MODx, Revolution will not install directly from Git. Because of the nature of the new packaging and installation system, you must first create the core installation package using a PHP build script before running the setup.
Git clone the revolution repository on GitHub at: http://github.com/modxcms/revolution/ using this syntax:
Or, if you'd like to contribute back, fork it in your GitHub repository and clone that repository with and add the modxcms/revolution repository as a remote called "upstream":
Forking it with your GitHub account will allow you to contribute back to MODx by sending pull requests by clicking the "Pull Request" button on your GitHub page. (You'll need to submit a CLA before we can accept your code, though.) If you decide to fork, it'd be helpful for you to read our Git Contributors Guide for detailed information on keeping your fork up-to-date.
From there, make sure you are working on the develop branch, if you're wanting the latest bugfixes and features targeted for the next release. There are two permanent branches in the modxcms/revolution GitHub repository:
- master - This will always match the latest production release; ie, 2.0.0-pl. It is the stable branch, and is only changed during releases.
- develop - The latest development branch Revolution; all new features and bug fixes targeted for the next release will exist here.
To create a local tracking branch from one in the origin remote; after cloning, just type:
And git will handle the rest.
|There will be other temporary branches in the repository from time to time, representing features in development, specific releases being prepared, and/or critical bug fixes for production releases.|
If this is the first time you are building from Git, copy the file _build/build.config.sample.php to _build/build.config.php and edit the properties to point at a valid database with proper credentials (since Revolution 2.1.x, you either need to copy & edit the same way _build/build.sample.properties to _build/build.properties.php). NOTE that this database does not have to contain anything; the build script just needs to be able to make a connection to a MySQL database.
From the command line, change your working directory to _build/ and execute the command "php transport.core.php". If the PHP executable is not in your path, you will need to either edit the path or give the full path to the PHP executable in the command line. The build process may take an extended period of time (10 to 30 seconds likely), so be patient. (Note: on Mac Mini (1.66Ghz Intel Core Duo with 2GB RAM) running the Leopard development environment as outlined below, this only takes 5-10 seconds.)
|Note that you can also do this from the browser by browsing to the _build/transport.core.php directory, if that directory is accessible in your web server setup.|
Once that script is finished executing, confirm that you now have a file named core/packages/core.transport.zip and a directory core/packages/core/ containing a manifest.php and many other files/directories.
Now you are ready to execute the new setup script at the setup/ URL (e.g. http://localhost/modxrevo/setup/ if installed in a subdirectory of the web root named modxrevo/).
|Make sure you check both the "Core package has been manually unpacked" and "Files are already in-place" options when installing from Git.|
If you change any paths on the Context Paths setup step, make sure and move the corresponding directories as appropriate; this is intended for installs from the core package with files not already in-place, where the installer will place the files in the specified locations (assuming the locations allow the PHP process to write to them).
|The actual install process requires more than the default 8M of memory allocated to PHP in many default php.ini files; if you get a blank page when you click "install", try increasing the memory_limit configuration to 32M or more (16M may work, but why not give php a little space, eh?).|
Simply run these two commands:
And Git will update your install. (Substitute 'release-2.1' for 'develop' if you're testing/contributing to a specific release branch, or whatever branch you might be working from.)
|If you're working from a fork, rather than straight from the modxcms/revolution repository, you'll have to fetch from upstream, rather than origin (since origin is your fork). Please read the [MODx GitHub Contributor's Guide] for more information.|
When a commit is made, this message might show up in the commit:
- [ReUp] - If your updates require a core transport rebuild (such as anything modified in the _build directory, database model changes, or default data changes), then prefix your commit message with this. If you see this message, simply rebuild the core transport and run setup/ again.
If this message does not show up, you're done after you fetch and rebase.
If you've fixed a bug or added an improvement, and you're working on a fork of the revolution repository, you can send a pull request to MODx and one of the Integration Managers will review your patch.
|You'll need to submit a CLA before we can accept your code.|
MODx recommends you to work on features or bugs in their own separate branches. This way, if MODx doesn't accept your pull request exactly as-is, but still updates those files, you wont have to 'git checkout' the develop (or whatever) branch over again. You can just trash the bugfix/feature branch and reload from your clean develop branch.
For example, lets say you want to add a feature for workflow for MODx. You'd create a local branch from the 'develop' branch called 'myworkflow' with:
...and then do your coding there. Once you're done, you'd push that branch to your fork, and then send the Pull Request over. Once MODx has integrated your code (or rejected it and you're finished with it), you can then delete the branch like so:
The first step takes us back to the develop branch, and then deletes the custom branch. This allows you to easily update MODx without having to worry about invalid or no-longer used commits, and keeps your main branch clean.
|You can always "git merge -|
For more information on using GitHub forks, see the GitHub Forking Help Page.
If you want to switch to a different branch (that you have already checked out locally), simply type these commands:
Of course, replacing release-2.1 with the actual name of the branch you want to switch to. After you've done so, run the build and run setup/ again, since different branches might have different databases.
|Switching backwards is not always recommended; ie, switching from develop (the latest) to release-2.0.4, since database changes don't always necessarily 'backport'. While no major issues should occur, be careful when doing this.|
If you use MAMP on Mac OS X, you may get problems (errors about DYLD libraries not being included) when trying to execute ''transport.core.php'' from the terminal. This is because the MAMP PHP libraries won't be on the dynamic linker path by default.
To adjust the dynamic linker library path to include the MAMP PHP libraries, run the following command via the terminal:
You can then execute ''transport.core.php'' by using the absolute path to the MAMP PHP executable: