RMT – Release Management Tool

RMT is a handy tool to help releasing new versions of your software. You can define the type
of version generator you want to use (e.g. semantic versioning), where you want to store
the version (e.g. in a changelog file or as a VCS tag) and a list of actions that should be
executed before or after the release of a new version.

Installation

Option 1: As a development dependency of your project

In order to use RMT in your project you should use Composer to install it
as a dev-dependency. Just go to your project’s root directory and execute:

composer require --dev liip/rmt

Then you must initialize RMT by running the following command:

php vendor/liip/rmt/command.php init

This command will create a .rmt.yml config file and a RMT executable script in your project’s
root folder. You can now start using RMT by executing:

./RMT

Once there, your best option is to pick one of the configuration examples below
and adapt it to your needs.
If you are using a versioning tool, we recommend to add both Composer files (composer.json
and composer.lock), the RMT configuration file(.rmt.yml) and the RMT executable script
to it. The vendor directory should be ignored as it is populated when running
composer install.

Option 2: As a global Composer installation

You can add RMT to your global composer.json and have it available globally for all your projects. Therefor
just run the following command:

composer global require liip/rmt

Make sure you have ~/.composer/vendor/bin/ in your $PATH.

Option 3: As a Phar file

RMT can be installed through phar-composer, which needs to be installed therefor. This useful tool allows you to create runnable Phar files from Composer packages.
If you have phar-composer installed, you can run:

sudo phar-composer install liip/RMT

and have phar-composer build and install the Phar file to your $PATH, which then allows you to run it simply as rmt from the command line or you can run

phar-composer build liip/RMT

and copy the resulting Phar file manually to where you need it (either make the Phar file executable via chmod +x rmt.phar and execute it
directly ./rmt.phar or run it by invoking it through PHP via php rmt.phar.
For the usage substitute RMT with whatever variant you have decided to use.

Option 4: As Drifter role

If your are using https://github.com/liip/drifter for your project, you just need three step

Activate the rmt role
Re-run the provisionning vagrant provision
Init RMT for your project php /home/vagrant/.config/composer/vendor/liip/rmt/RMT

Usage

Using RMT is very straightforward, just run the command:

./RMT release

RMT will then execute the following tasks:

Execute the prerequisites checks
Ask the user to answers potentials questions
Execute the pre-release actions
Release
- Generate a new version number
- Persist the new version number
Execute the post-release actions

Here is an example output:

Additional commands

The release command provides the main behavior of the tool, additional some extra commands are available:

current will show your project current version number (alias version)
changes display the changes that will be incorporated in the next release
config display the current config (already merged)
init create (or reset) the .rmt.yml config file

Configuration

All RMT configurations have to be done in .rmt.yml. The file is divided in six root elements:

vcs: The type of VCS you are using, can be git, svn or none
- For git VCS you can use the two following options sign-tag and sign-commit if you want to GPG sign your release
prerequisites: A list [] of prerequisites that must be matched before starting the release process
pre-release-actions: A list [] of actions that will be executed before the release process
version-generator: The generator to use to create a new version (mandatory)
version-persister: The persister to use to store the versions (mandatory)
post-release-actions: A list [] of actions that will be executed after the release

All entries of this config work the same. You have to specify the class you want to handle the action. Example:

version-generator: "simple"`
version-persister:
   vcs-tag:
       tag-prefix: "v_"

RMT also support JSON configs, but we recommend using YAML.

Branch specific config

Sometimes you want to use a different release strategy according to the VCS branch, e.g. you want to add CHANGELOG entries only in the master branch. To do so, you have to place your default config into a root element named _default, then you can override parts of this default config for the
branch master. Example:

_default:
    version-generator: "simple"
    version-persister: "vcs-tag"
master:
    pre-release-actions: [changelog-update]

You can use the command RMT config to see the merge result between _default and your current branch.

Version generator

Build-in version number generation strategies.

simple: This generator is doing a simple increment (1,2,3…)

semantic: A generator which implements Semantic versioning

Option allow-label (boolean): To allow adding a label on a version (such as -beta, -rcXX) (default: false)
Option type: to force the version type
Option label: to force the label

<p>
  The two forced option could be very useful if you decide that a given branch is dedicated to the next beta of a<br /> given version. So just force the label to beta and all release are going to be beta increments. </li> </ul> 
  
  <h3 dir="auto">
    <a rel="nofollow noopener" target="_blank" id="user-content-version-persister" class="anchor" aria-hidden="true" href="#version-persister"></a>Version persister
  </h3>
  
  <p>
    Class in charge of saving/retrieving the version number.
  </p>
  
  <ul dir="auto">
    <li>
      vcs-tag: Save the version as a VCS tag</p> <ul dir="auto">
        <li>
          Option <code>tag-pattern</code>: Allow to provide a regex that all tag must match. This allow for example to release a version 1.X.X in a specific branch and to release a 2.X.X in a separate branch
        </li>
        <li>
          Option <code>tag-prefix</code>: Allow to prefix all VCS tag with a string. You can have a numeric versionning but generation tags such as <code>v_2.3.4</code>. As a bonus you can use a specific placeholder: <code>{branch-name}</code> that will automatically inject the current branch name in the tag. So use, simple generation and <code>tag-prefix: "{branch-name}_"</code> and it will generate tag like <code>featureXY_1</code>, <code>featureXY_2</code>, etc&#8230;
        </li>
      </ul>
    </li>
    
    <li>
      changelog: Save the version in the changelog file</p> <ul dir="auto">
        <li>
          Option <code>location</code>: Changelog file name an location (default: CHANGELOG)
        </li>
      </ul>
    </li>
  </ul>
  
  <h3 dir="auto">
    <a rel="nofollow noopener" target="_blank" id="user-content-prerequisite-actions" class="anchor" aria-hidden="true" href="#prerequisite-actions"></a>Prerequisite actions
  </h3>
  
  <p>
    Prerequisite actions are executed before the interactive part.
  </p>
  
  <ul dir="auto">
    <li>
      <code>working-copy-check</code>: check that you don&#8217;t have any VCS local changes</p> <ul dir="auto">
        <li>
          Option <code>allow-ignore</code>: allow the user to skip the check when doing a release with <code>--ignore-check</code>
        </li>
      </ul>
    </li>
    
    <li>
      <code>display-last-changes</code>: display your last changes
    </li>
    <li>
      <code>tests-check</code>: run the project test suite</p> <ul dir="auto">
        <li>
          Option <code>command</code>: command to run (default: phpunit)
        </li>
        <li>
          Option <code>timeout</code>: the number of seconds after which the command times out (default: 60.0)
        </li>
        <li>
          Option <code>expected_exit_code</code>: expected return code (default: 0)
        </li>
      </ul>
    </li>
    
    <li>
      <code>composer-json-check</code>: run a validate on the composer.json</p> <ul dir="auto">
        <li>
          Option <code>composer</code>: how to run composer (default: php composer.phar)
        </li>
      </ul>
    </li>
    
    <li>
      <code>composer-stability-check</code>: will check if the composer.json is set to the right minimum-stability</p> <ul dir="auto">
        <li>
          Option <code>stability</code>: the stability that should be set in the minimum-stability field (default: stable)
        </li>
      </ul>
    </li>
    
    <li>
      <code>composer-security-check</code>: run the composer.lock against https://github.com/fabpot/local-php-security-checker to check for known vulnerabilities in the dependencies. ⚠️ The local-php-security-checker binary must be installed globally.
    </li>
    <li>
      <code>composer-dependency-stability-check</code>: test if only allowed dependencies are using development versions</p> <ul dir="auto">
        <li>
          Option <code>ignore-require</code> and <code>ignore-require-dev</code>: don&#8217;t check dependencies in <code>require</code> or <code>require-dev</code> section
        </li>
        <li>
          Option <code>whitelist</code>: allow specific dependencies to use development version
        </li>
      </ul>
    </li>
    
    <li>
      <code>command</code>: Execute a system command</p> <ul dir="auto">
        <li>
          Option <code>cmd</code> The command to execute
        </li>
        <li>
          Option <code>live_output</code> boolean, do we display the command output? (default: true)
        </li>
        <li>
          Option <code>timeout</code> integer, limits the time for the command. (default: 600)
        </li>
        <li>
          Option <code>stop_on_error</code> boolean, do we break the release process on error? (default: true)
        </li>
      </ul>
    </li>
  </ul>
  
  <h3 dir="auto">
    <a rel="nofollow noopener" target="_blank" id="user-content-actions" class="anchor" aria-hidden="true" href="#actions"></a>Actions
  </h3>
  
  <p>
    Actions can be used for pre or post release&#8230;
  </p>