NAME
App::git::ship - Git command for shipping your project
VERSION
0.23
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.
This project can also "start" (create) a new project, just "build"
(prepare for shipping), "ship" (upload), and "clean" projects.
App::git::ship differs from other tools like dzil by not enforcing new
ways to do things, but rather incorporates with the existing way.
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 .ship.conf "project_name"
and "license". "AUTHOR" will have the name and email from the last
git committer. "ABSTRACT_FROM" and "VERSION_FROM" are fetched from
the main_module_path. "EXE_FILES" will be the files in "bin/" and
"script/" which are executable. "META_MERGE" will use data from
"bugtracker", "homepage", and "repository". It is important to
define your license in your .ship.conf before starting.
Both "cpanfile" and "Makefile.PL" are automatically created for you
if you set the class to App::git::ship::perl or you specify the
main_module_path as an argument to git start.
* my-app/CHANGELOG.md or my-app/Changes
The Changes file will be updated with the correct timestamp, from
when you ran the "build" action. The Changes file will also be the
source for "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.
Changes is automatically created for you if you set the class to
App::git::ship::perl or your specify the main_module_path as an
argument to git start.
* my-app/README
Will be updated with the main module documentation using the command
below:
$ perldoc -tT $main_module_path > README;
If you don't like this format, you can create and write "README.md"
manually instead. The presense of that file will prevent
"my-app/README" from getting generated.
Both "README" and "README.pod" are automatically created for you if
you set the class to App::git::ship::perl or your specify the
main_module_path as an argument to git start.
* 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.
It is important to have a remote setup in your git repository before
shipping. It is important to have a ~/.pause file setup with 'user'
and 'password' entries before shipping.
SYNOPSIS
Existing project
# Set up git ship config and basic files for a Perl repo
$ cd my-project
$ git ship start lib/My/Project.pm
# 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
New project
$ git ship -h
$ git ship start My/Project.pm
$ cd my-project
# 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
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
For developer
package App::git::ship::some_language;
use App::git::ship -base;
# define attributes
has some_attribute => sub {
my $self = shift;
return "default value";
};
# override the methods defined in App::git::ship
sub build {
my $self = shift;
}
1;
CONFIG
"App::git::ship" automatically generates a config file when you "start"
a new project.
* bugtracker
URL to the bugtracker for this project.
* 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
* 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.
* homepage
URL to the home page for this project.
* license
The name of the license to use. Defaults to "artistic_2".
* 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".
* 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:
project_name = My::App
* Comments
Comments are made by adding the hash symbol (#) followed by text. If
you want to use the "#" as a value, it needs to be escaped using
"\#". Examples:
# This whole line is skipped
parameter = 123 # The end of this line is skipped
parameter = some \# value with hash
* Hooks
It is possible to add hooks to the "CONFIG" file. These hooks are
programs that runs in your shell. Example .ship file with hooks:
before_build = bash script/new-release.sh
after_build = rm -r lib/My/App/templates lib/My/App/public
after_ship = cat Changes | mail -s "Changes for My::App" all@my-app.com
Possible hooks are "before_build", "after_build", "before_ship", and
"after_ship".
ATTRIBUTES
config
$hash_ref = $self->config;
Holds the configuration from end user. The config is by default read
from ".ship.conf" in the root of your project.
next_version
$str = $self->next_version;
Holds the next version to "ship".
project_name
$str = $self->project_name;
Holds the name of the current project. This attribute can be read from
"config".
repository
$str = $self->repository;
Returns the URL to the first repository that points to "origin". This
attribute can be read from "config".
The username is detected by the uid on your OS, you can override this by
setting GITHUB_USERNAME.
silent
$bool = $self->silent;
$self = $self->silent($bool);
Set this to true if you want less logging. By default silent is false.
METHODS
abort
$self->abort($str);
$self->abort($format, @args);
Will abort the application run with an error message.
attr
$class = $class->attr($name => sub { my $self = shift; return $default_value });
or ...
use App::git::ship -base;
has $name => sub { my $self = shift; return $default_value };
Used to create an attribute with a lazy builder.
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.
detect
$class = $self->detect;
$class = $self->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.
run_hook
$self->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
new
$self = $class->new(%attributes);
Creates a new instance of $class.
render
$self->render($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.
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
$self->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.
import
use App::git::ship;
use App::git::ship -base;
use App::git::ship "App::git::ship::perl";
Called when this class is used. It will automatically enable strict,
warnings, utf8 and Perl 5.10 features.
"-base" will also make sure the calling class inherits from
App::git::ship and gets the has function. Does the same with a class
name, except that it will then inherit from the given class.
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-2016, 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"