Why not adopt me?
NAME
setup-travis-yml.pl - Tool for managing .travis.yml files
VERSION
version 0.19
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:
addons
An addons
block will be added or updated to include aspell
and aspell-en
for the benefit of Test::Spelling.
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) 2019 by MaxMind, Inc.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)