/ 
Dist-Zilla-TravisCI-1.15
River stage one • 3 direct dependents • 4 total dependents
/ Dist::Zilla::Plugin::Travis::TestRelease

NAME

Dist::Zilla::Plugin::Travis::TestRelease - makes sure repo passes Travis tests before release

SYNOPSIS

   ;;; Test DZIL

   [Travis::TestRelease]
   ; defaults typically work fine

   ;;; Test DZIL+build

   [TravisYML]
   support_builddir = 1
   ; (optional) only test with Travis::TestRelease
   dzil_branch = /^release_testing\/.*/

   [Travis::TestRelease]
   create_builddir = 1

DESCRIPTION

Tired of releasing a module only to discover that it failed Travis tests? This plugin solves that problem.

It pushes a release testing branch to Travis, monitors the testing, and aborts the release if the Travis build fails. It also supports testing the non-DZIL build directory directly.

TravisYML is not required to use this plugin, even for build testing, but is still recommended.

DETAILS

Starting the process requires creating and pushing a release testing branch to GitHub. This is done through a series of git commands, designed to work with the dirtiest of branch states:

  1. If there are any "dirty files", even untracked files, put them into a git stash.

  2. Create or hard reset the release testing branch to match the main branch.

  3. Apply the stash (if created) and add any new files.

  4. If a build directory is requested, extract it into .build/testing, and add it.

  5. Commit the changes.

  6. Force push the testing branch to the repo.

  7. Switch back to the main branch.

  8. If any files were stashed, apply it back to the branch. This is done by hard resetting the main branch to the stash (don't panic; it's just a copy of the branch with a few extra commits), and then walking the index back to the refhash it was at originally.

As you may notice, the testing branch is subject to harsh and overwriting changes, so don't rely on the branch for anything except release testing!

After the branch is pushed, the plugin checks Travis (via API) to make sure it starts testing. Monitoring stops when Travis says the build is finished. Use of Travis' Fast Finish option is recommended to speed up test results.

OPTIONS

remote

Name of the remote repo.

The default is origin.

branch

Name of the local release testing branch. Do not use this branch for anything except release testing!

The default is release_testing/$current_branch.

remote_branch

Name of the remote branch.

The default is whatever the branch option is set to.

slug

Name of the "slug", or username/repo combo, that will be used to query the test details. For example, this distro has a slug of SineSwiper/Dist-Zilla-TravisCI.

The default is auto-detection of the slug using the remote URL.

create_builddir

Boolean; determines whether to create a build directory or not. If turned on, the plugin will create a .build/testing directory in the testing branch to be used for build testing. Whether this is actually used depends on the .travis.yml file. For example, TravisYML's support_builddir switch will create a Travis matrix in the YAML file to test both DZIL and build directories on the same git branch. If you're not using that plugin, you should at least implement something similar to make use of dual DZIL+build tests.

Default is off.

open_status_url

Boolean; determines whether to automatically open the Travis CI build status URL to a browser, using Browser::Open.

Default is off.

CAVEATS

Plugin order is important. Since Travis build testing takes several minutes, this should be one of the last before_release plugins in your dist.ini, after plugins like TestRelease, but still just before ConfirmRelease.

The amount of git magic and little used switches required to make and push the branch to GitHub may be considered questionable by some, especially force pushes and hard resets. But it is all required to make sure testing occurs from any sort of branch state. And it works.

Furthermore, it's not the job of this plugin to make sure the branch state is clean. Use plugins like Git::Check for that.

AVAILABILITY

The project homepage is https://github.com/SineSwiper/Dist-Zilla-TravisCI.

The latest version of this module is available from the Comprehensive Perl Archive Network (CPAN). Visit http://www.perl.com/CPAN/ to find a CPAN site near you, or see https://metacpan.org/module/Dist::Zilla::TravisCI/.

AUTHOR

Brendan Byrd <bbyrd@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2015 by Brendan Byrd.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)