NAME

App::git::ship - Git command for shipping your project

VERSION

0.28

DESCRIPTION

App::git::ship is a git command for building and shipping your project.

The main focus is to automate away the boring steps, but at the same time not get in your (or any random contributor's) way. Problems should be solved with sane defaults according to standard rules instead of enforcing more rules.

App::git::ship differs from other tools like dzil by not requiring any configuration except for a file containing the credentials for uploading to CPAN.

Example structure and how App::git::ship works on your files:

• my-app/cpanfile and my-app/Makefile.PL

  The cpanfile is used to build the "PREREQ_PM" and "BUILD_REQUIRES" structures in the ExtUtils::MakeMaker based Makefile.PL build file. The reason for this is that cpanfile is a more powerful format that can be used by Carton and other tools, so generating cpanfile from Makefile.PL would simply not be possible. Other data used to generate Makefile.PL are:

  "NAME" and "LICENSE" will have values from "GIT_SHIP_PROJECT_NAME" and "GIT_SHIP_LICENSE". "AUTHOR" will have the name and email from "GIT_SHIP_AUTHOR" or the last git committer. "ABSTRACT_FROM" and "VERSION_FROM" are fetched from the "main_module_path" in App::git::ship::perl. "EXE_FILES" will be the files in bin/ and script/ which are executable. "META_MERGE" will use data from "GIT_SHIP_BUGTRACKER", "GIT_SHIP_HOMEPAGE", and "repository".

• my-app/Changes or my-app/CHANGELOG.md

  The Changes file will be updated with the correct GIT_SHIP_NEW_VERSION_FORMAT, from when you ran the "build" action. The Changes file will also be the source for "GIT_SHIP_NEXT_VERSION". Both CHANGELOG.md and Changes are valid sources. App::git::ship looks for a version-timestamp line with the case-sensitive text "Not Released" as the the timestamp.

• my-app/lib/My/App.pm

  This file will be updated with the version number from the Changes file.

• .gitignore and MANIFEST.SKIP

  Unless these files exist, they will be generated from a template which skips the most common files. The default content of these two files might change over time if new temp files are created by new editors or some other formats come along.

• t/00-basic.t

  Unless this file exists, it will be created with a test for checking that your modules can compile and that the POD is correct. The file can be customized afterwards and will not be overwritten.

• .git

  It is important to commit any uncommitted code to your git repository beforing building and that you have a remote setup in your git repository before shipping.

• .pause

  You have to have a $HOME/.pause file before shipping. It should look like this:

    user yourcpanusername
    password somethingsupersecret

SYNOPSIS

git ship

  # Set up basic files for a Perl repo
  # (Not needed if you already have an existing repo)
  $ git ship start lib/My/Project.pm
  $ git ship start

  # Make changes
  $ $EDITOR lib/My/Project.pm

  # Build first if you want to investigate the changes
  $ git ship build

  # Ship the project to git (and CPAN)
  $ git ship ship

Git aliases

  # git build
  $ git config --global alias.build = ship build

  # git cl
  $ git config --global alias.cl = ship clean

  # git start
  # git start My/Project.pm
  $ git config --global alias.start = ship start

ENVIRONMENT VARIABLES

Environment variables can also be set in a config file named .ship.conf, in the root of the project directory. The format is:

  # some comment
  bugtracker = whatever
  new_version_format = %v %Y-%m-%dT%H:%M:%S%z

Any of the keys are the same as all the "ENVIRONMENT VARIABLES", but without "GIT_SHIP_".

GIT_SHIP_AFTER_SHIP

It is possible to add hooks. These hooks are programs that runs in your shell. Example hooks:

  GIT_SHIP_AFTER_SHIP="bash script/new-release.sh"
  GIT_SHIP_AFTER_BUILD="rm -r lib/My/App/templates lib/My/App/public"
  GIT_SHIP_AFTER_SHIP="cat Changes | mail -s "Changes for My::App" all@my-app.com"

GIT_SHIP_AFTER_BUILD

See "GIT_SHIP_AFTER_SHIP".

GIT_SHIP_AUTHOR

See "author".

GIT_SHIP_BEFORE_BUILD

See "GIT_SHIP_AFTER_SHIP".

GIT_SHIP_BEFORE_SHIP

See "GIT_SHIP_AFTER_SHIP".

GIT_SHIP_BUGTRACKER

URL to the bugtracker for this project.

GIT_SHIP_BUILD_TEST_OPTIONS

This holds the arguments for the test program to use when building the project. The default is to not automatically run the tests. Example value:

  build_test_options = -l -j4

GIT_SHIP_CHANGELOG_FILENAME

Defaults to either "CHANGELOG.md" or "Changes".

GIT_SHIP_CLASS

This class is used to build the object that runs all the actions on your project. This is autodetected by looking at the structure and files in your project. For now this value can be App::git::ship or App::git::ship::perl, but any customization is allowed.

GIT_SHIP_DEBUG

Setting this variable will make "git ship" output more information.

GIT_SHIP_HOMEPAGE

URL to the home page for this project.

GIT_SHIP_LICENSE

The name of the license to use. Defaults to "artistic_2".

GIT_SHIP_MAIN_MODULE_PATH

Path tot the main module in your project.

GIT_SHIP_NEW_VERSION_FORMAT

This is optional, but specifies the version format in your "Changes" file. The example below will result in "## 0.42 (2014-01-28)".

  new_version_format = \#\# %v (%F)

"%v" will be replaced by the version, while the format arguments are passed on to "strftime" in POSIX.

The default is "%v %Y-%m-%dT%H:%M:%S%z".

GIT_SHIP_NEXT_VERSION

Defaults to the version number in "GIT_SHIP_MAIN_MODULE_PATH" + "0.01".

GIT_SHIP_PROJECT_NAME

This name is extracted from either the "main_module_path" in App::git::ship::perl or defaults to "unknown" if no project name could be found. Example:

GIT_SHIP_SILENT

Setting this variable will make "git ship" output less information.

GIT_SHIP_USERNAME

METHODS

abort

  $ship->abort($str);
  $ship->abort($format, @args);

Will abort the application run with an error message.

build

This method builds the project. The default behavior is to "abort". Needs to be overridden in the subclass.

can_handle_project

  $bool = $class->can_handle_project($file);

This method is called by "detect" in App::git::ship and should return boolean true if this module can handle the given git project.

This is a class method which gets a file as input to detect or have to auto-detect from current working directory.

config

  $hash_ref = $ship->config;
  $str      = $ship->config($name);
  $self     = $ship->config($name => $value);

Holds the configuration from end user. The config is by default read from .ship.conf in the root of your project.

detect

  $class = $ship->detect;
  $class = $ship->detect($file);

Will detect the module which can be used to build the project. This can be read from the "class" key in "config" or will in worse case default to App::git::ship.

dump

  $str = $ship->dump($any);

Will serialize $any into a perl data structure, using Data::Dumper.

new

  $ship = App::git::ship->new(\%attributes);

Creates a new instance of $class.

render_template

  $ship->render_template($file, \%args);

Used to render a template by the name $file to a $file. The template needs to be defined in the DATA section of the current class or one of the super classes.

run_hook

  $ship->run_hook($name);

Used to run a hook before or after an event. The hook is a command which needs to be defined in the config file. Example config line parameter:

  before_build = echo foo > bar.txt

ship

  $ git ship ship

This method ships the project to some online repository. The default behavior is to make a new tag and push it to "origin". Push occurs only if origin is defined in git.

start

This method is called when initializing the project. The default behavior is to populate "config" with default data:

• bugtracker

  URL to the bug tracker. Will be the the "repository" URL without ".git", but with "/issues" at the end instead.

• homepage

  URL to the project homepage. Will be the the "repository" URL, without ".git".

• license

  The name of the license. Defaults to artistic_2.

  See "license" in CPAN::Meta::Spec for alternatives.

system

  $ship->system($program, @args);

Same as perl's system(), but provides error handling and logging.

test_coverage

This method checks test coverage for the project. The default behavior is to "abort". Needs to be overridden in the subclass.

SEE ALSO

• Dist::Zilla

  This project can probably get you to the moon.

• Minilla

  This looks really nice for shipping your project. It has the same idea as this distribution: Guess as much as possible.

• Shipit

  One magical tool for doing it all in one bang.

COPYRIGHT AND LICENSE

Copyright (C) 2014-2018, Jan Henning Thorsen

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.

AUTHOR

Jan Henning Thorsen - jhthorsen@cpan.org

cpanm App::git::ship

perl -MCPAN -e shell
install App::git::ship