NAME

setup-travis-yml.pl - Tool for managing .travis.yml files

VERSION

version 0.15

DESCRIPTION

This script updates existing .travis.yml files or creates a new one based on various settings from the command line. It is mostly focused on configuring Perl projects to work with the Perl Travis Helpers tools. It also reorders the top-level keys in the YAML file and does some other minor cleanups.

GETTING STARTED

You can create a new file for a Perl build from scratch by running this script with the --create argument:

    $> setup-travis-yml.pl --dir . --create

If you want to update one or more existing files, don't pass --create.

If you want email or slack notification you'll need to pass a few more arguments:

    $> setup-travis-yml.pl \
           --github-user example \
           --slack-key o8PZMLqZK6uWVxyyTzZf4qdY \
           --email-address example@example.org

THE CONFIG

If there is an existing file, most of its config will be preserved. The existing config is used as the guide for some decisions about what to update, as detailed below. A newly created file will also follow this guide.

Here's a step-by-step guide to the generated Travis config and what it does:

sudo and addons

By default, sudo will be disabled for the Travis run. This makes Travis faster. However, if an existing before_install or install block invokes sudo, then sudo will be enabled.

When sudo is disabled, the addons block will be updated to include aspell and aspell-en for the benefit of Test::Spelling.

If sudo is enabled, then you'll need to make sure your config installs any Debian packages which are needed.

before_install, install, and script

If this exists and does not mention either travis-perl (the new name) or perl-travis-helper (the old name), then these blocks will be left as-is.

If the travis-perl helpers are referenced, the following updates are done:

If the script block is more than 3 lines long and either the install block is longer than 2 lines or the install block does not contain a call to the travis-perl cpan-install, then the before_install block is updated to include these lines:

    - git clone git://github.com/travis-perl/helpers ~/travis-perl-helpers
    - source ~/travis-perl-helpers/init

If there are existing travis-perl clone and source lines, these will be replaced with the two lines above. Otherwise these two lines will be inserted at the beginning of the block.

This is how you would start using the travis-perl helpers in the non-auto (long) config.

If the script and install blocks don't match the aforementioned conditions, then the instal and script blocks are deleted entirely and the before_install block is updated to contain this line:

    - eval $(curl https://travis-perl.github.io/init) --auto --always-upgrade-modules

If there is an existing travis-perl eval line, this will be replaced with the line above. Otherwise this line will be inserted at the beginning of the block.

perl and matrix

The perl block will be updated based on the following rules:

If your distro does not have XS and you did not force the use of threaded Perls, then you get a block like this:

    perl:
      - blead
      - dev
      - '5.26'
      - '5.24'
      - '5.22'
      - '5.20'
      - '5.18'
      - '5.16'
      - '5.14'

If the distro has XS code or you pass the --force-threaded-perls command line argument, then you will get a block with every Perl from 5.14 to the latest stable release, plus dev and blead, in both threaded and unthreaded forms. This will look something like this:

    perl:
      - blead
      - blead-thr
      - dev
      - dev-thr
      - 5.26.0
      - 5.26.0-thr
      - 5.24.1
      - 5.24.1-thr
      - 5.22.3
      - 5.22.3-thr
      - 5.20.3
      - 5.20.3-thr
      - 5.18.3
      - 5.18.3-thr
      - 5.16.3
      - 5.16.3-thr
      - 5.14.4
      - 5.14.4-thr

In either case, you will also get a matrix block that is configured to allow failures for all blead runs. It will also include a run with COVERAGE=1 in the environment against the latest stable Perl version, so something like this:

    matrix:
      allow_failures:
        - perl: blead
      include:
        - env: COVERAGE=1
          perl: '5.26'

env.global

This script will ensure that env.global sets both RELEASE_TESTING=1 and AUTHOR_TESTING=1, in addition to any other variables you have listed. It will also sort the entries in this block.

notifications

If you pass an --email-address or --slack-key command line argument, then this block will be updated. For email, notifications will be sent on all failures and on changes.

If you pass a slack key the travis command line tool will be executed to encrypt the key and it will be added to the config. If you have an existing secure key it will not be updated, because the travis tool generates a new encrypted key every time it's invoked, leading to annoying churn.

__app_cisetup__ comment

This saves any flags you pass on the command line. Future runs of this script will use these flags. However, CLI flags will always take precedence over these.

ARGUMENTS

This script accepts the following command line arguments:

--create

Create a new file instead of updating existing ones.

--dir

The directory under which to look for .travis.yml files. This does a recursive search so you can update many projects at once. In create mode it will only create a file in the current directory.

This is required.

--force-threaded-perls

Force the inclusion of both threaded and unthreaded Perls in the generated config, regardless of whether the distro has XS or not.

--perl-caching

If this is true, then a cache block will added to cache the $HOME/perl5 directory. In addition, the travis-perl init call will be updated to add --always-uprade-modules.

Caching is enabled for Perl projects by default, but you can disable this by passing --no-perl-caching.

--slack-key

A Slack key to use for Slack notifications. If you pass this you must also pass --github-user.

You'll need to have the Travis CLI installed. On a linux box this would be something like

    $> sudo apt-get install ruby1.9.1-dev
    $> sudo gem install travis -v 1.8.2 --no-rdoc --no-ri

--github-user

Your github user name. This is required if you pass --slack-key.

--email-address

The email address to which notifications should be sent. This is optional, and if you don't provide it, then no notification emails will be configured (but the default Travis notifications will still be in place).

SUPPORT

Bugs may be submitted through https://github.com/maxmind/App-CISetup/issues.

AUTHORS

• Mark Fowler <mark@twoshortplanks.com>

• Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2018 by MaxMind, Inc.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

cpanm App::CISetup

perl -MCPAN -e shell
install App::CISetup