From: Graham Knop Date: Sat, 5 Dec 2015 23:56:32 +0000 (-0500) Subject: docs X-Git-Tag: v0.003000~39 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit%2FDistar.git;a=commitdiff_plain;h=edb4539ab17337bdc7b1f64aded94b1c48b75a59 docs --- diff --git a/lib/Distar.pm b/lib/Distar.pm index 5aba3ce..dc0a9b8 100644 --- a/lib/Distar.pm +++ b/lib/Distar.pm @@ -180,3 +180,198 @@ END } 1; +__END__ + +=head1 NAME + +Distar - Additions to ExtUtils::MakeMaker for dist authors + +=head1 SYNOPSIS + +F: + + use ExtUtils::MakeMaker; + (do 'maint/Makefile.PL.include' or die $@) unless -f 'META.yml'; + + WriteMakefile(...); + +F: + + BEGIN { -e 'Distar' or system("git clone git://git.shadowcat.co.uk/p5sagit/Distar.git") } + use lib 'Distar/lib'; + use Distar 0.001; + + author 'A. U. Thor '; + + manifest_include t => 'test-helper.pl'; + manifest_include corpus => '.txt'; + +make commmands: + + $ perl Makefile.PL + $ make bump # bump version + $ make bump V=2.000000 # bump to specific version + $ make bumpminor # bump minor version component + $ make bumpmajor # bump major version component + $ make nextrelease # add version heading to Changes file + $ make releasetest # build dist and test (with xt/ and RELEASE_TESTING=1) + $ make preflight # check that repo and file state is release ready + $ make release # check releasetest and preflight, then build and + # upload to CPAN, tag release, push tag and branch + +=head1 DESCRIPTION + +L works well enough as development tool for +builting and testing, but using it to release is annoying and error prone. +Distar adds just enough to L for it to be a usable dist +author tool. This includes extra commands for releasing and safety checks, and +automatic generation of some files. It doesn't require any non-core modules and +is compatible with old versions of perl. + +=head1 FUNCTIONS + +=head2 author( $author ) + +Set the author to include in generated META files. Can be a single entry, or +an arrayref. + +=head2 manifest_include( $dir, $pattern ) + +Add a pattern to include files in the MANIFEST file, and thus in the generated +dist files. + +The pattern can be either a regex, or a path suffix. It will be applied to the +full path past the directory specified. + +The default files that are always included are: F<.pm> and F<.pod> files in +F, F<.t> files in F and F, F<.pm> files in F and F, +F, F, F, F, F, and F<.PL> files in +the dist root, and all files in F. + +=head1 AUTOGENERATED FILES + +=over 4 + +=item F + +The F will be automatically generated to exclude any files not +explicitly allowed via C or the included defaults. It will be +created (or updated) at C time. + +=item F + +The F file will be generated at dist generation time, inside the built +dist. It will be generated using C on the main module. + +If a F file exists in the repo, it will be used directly instead of +generating the file. + +=back + +=head1 MAKE COMMMANDS + +=head2 test + +test will be adjusted to include F tests by default. This will only apply +for authors, not users installing from CPAN. + +=head2 release + +Releases the dist. Before releasing, checks will be done on the dist using the +C and C commands. + +Releasing will generate a dist tarball and upload it to CPAN using cpan-upload. +It will also create a git tag for the release, and push the tag and branch. + +=head2 preflight + +Performs a number of checks on the files and repository, ensuring it is in a +sane state to do a release. The checks are: + +=over 4 + +=item * All version numbers match + +=item * The F file is up to date + +=item * The branch is correct + +=item * There is no existing tag for the version + +=item * There are no unmerged upstream changes + +=item * There are no outstanding local changes + +=item * There is an appropriate staged Changes heading + +=item * cpan-upload is available + +=back + +=head2 releasetest + +Test the dist preparing for a release. This generates a dist dir and runs the +tests from inside it. This ensures all appropriate files are included inside +the dist. C will be set in the environment. + +=head2 nextrelease + +Adds an appropriate changelog heading for the release, and prompts to stage the +change. + +=head2 bump + +Bumps the version number. This will try to preserve the length and format of +the version number. The least significant digit will be incremented. + +Optionally accepts a C option to set the version to a specific value. + +The version changes will automatically be committed. Unstaged modifications to +the files will be left untouched. + +=head2 bumpminor + +Like bump, but increments the minor segment of the version. This will treat +numeric versions as x.yyyzzz format, incrementing the yyy segment. + +=head2 bumpmajor + +Like bumpminor, but bumping the major segment. + +=head2 refresh + +Updates Distar and re-runs C + +=head1 SUPPORT + +IRC: #web-simple on irc.perl.org + +Git repository: L + +Git browser: L + +=head1 AUTHOR + +mst - Matt S. Trout (cpan:MSTROUT) + +=head1 CONTRIBUTORS + +haarg - Graham Knop (cpan:HAARG) + +ether = Karen Etheridge (cpan:ETHER) + +frew - Arthur Axel "fREW" Schmidt (cpan:FREW) + +Mithaldu - Christian Walde (cpan:MITHALDU) + +=head1 COPYRIGHT + +Copyright (c) 2011-2015 the Distar L and L +as listed above. + +=head1 LICENSE + +This library is free software and may be distributed under the same terms +as perl itself. See L. + +=cut