--- /dev/null
+# NAME
+
+Distar - Additions to ExtUtils::MakeMaker for dist authors
+
+# SYNOPSIS
+
+`Makefile.PL`:
+
+ use ExtUtils::MakeMaker;
+ (do './maint/Makefile.PL.include' or die $@) unless -f 'META.yml';
+
+ WriteMakefile(...);
+
+`maint/Makefile.PL.include`:
+
+ 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 <author@cpan.org>';
+
+ 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, commits and tags,
+ # builds and uploads to CPAN, and pushes commits and
+ # tag
+ $ make release FAKE_RELEASE=1
+ # builds a release INCLUDING committing and tagging,
+ # but does not upload to cpan or push anything to git
+
+# DESCRIPTION
+
+[ExtUtils::MakeMaker](https://metacpan.org/pod/ExtUtils%3A%3AMakeMaker) 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 [ExtUtils::MakeMaker](https://metacpan.org/pod/ExtUtils%3A%3AMakeMaker) 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.
+
+# FUNCTIONS
+
+## author( $author )
+
+Set the author to include in generated META files. Can be a single entry, or
+an arrayref.
+
+## 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: `.pm` and `.pod` files in
+`lib`, `.t` files in `t` and `xt`, `.pm` files in `t/lib` and `xt/lib`,
+`Changes`, `MANIFEST`, `README`, `LICENSE`, `META.yml`, and `.PL` files in
+the dist root, and all files in `maint`.
+
+# AUTOGENERATED FILES
+
+- `MANIFEST.SKIP`
+
+ The `MANIFEST.SKIP` will be automatically generated to exclude any files not
+ explicitly allowed via `manifest_include` or the included defaults. It will be
+ created (or updated) at `perl Makefile.PL` time.
+
+- `README`
+
+ The `README` file will be generated at dist generation time, inside the built
+ dist. It will be generated using `pod2text` on the main module.
+
+ If a `README` file exists in the repo, it will be used directly instead of
+ generating the file.
+
+# MAKE COMMMANDS
+
+## test
+
+test will be adjusted to include `xt/` tests by default. This will only apply
+for authors, not users installing from CPAN.
+
+## release
+
+Releases the dist. Before releasing, checks will be done on the dist using the
+`preflight` and `releasetest` 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.
+
+### FAKE\_RELEASE
+
+If release is run with FAKE\_RELEASE=1 set, it will skip uploading to CPAN and
+pushing to git. A release commit will still be created and tagged locally.
+
+## 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:
+
+- All version numbers match
+- The `MANIFEST` file is up to date
+- The branch is correct
+- There is no existing tag for the version
+- There are no unmerged upstream changes
+- There are no outstanding local changes
+- There is an appropriate staged Changes heading
+- cpan-upload is available
+
+## 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. `RELEASE_TESTING` will be set in the environment.
+
+## nextrelease
+
+Adds an appropriate changelog heading for the release, and prompts to stage the
+change.
+
+## 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. Versions
+with underscores will preserve the underscore in the same position.
+
+Optionally accepts a `V` 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.
+
+### V
+
+The V option will be passed along to the version bumping script. It can accept
+a space separated list of options, including an explicit version number.
+
+Options:
+
+- --force
+
+ Updates version numbers even if they do not match the current expected version
+ number.
+
+- --stable
+
+ Attempts to convert the updated version to a stable version, removing any
+ underscore.
+
+- --alpha
+
+ Attempts to convert the updated version to an alpha version, adding an
+ underscore in an appropriate place.
+
+## bumpminor
+
+Like bump, but increments the minor segment of the version. This will treat
+numeric versions as x.yyyzzz format, incrementing the yyy segment.
+
+## bumpmajor
+
+Like bumpminor, but bumping the major segment.
+
+## refresh
+
+Updates Distar and re-runs `perl Makefile.PL`
+
+# SUPPORT
+
+IRC: #web-simple on irc.perl.org
+
+Git repository: [git://git.shadowcat.co.uk/p5sagit/Distar](git://git.shadowcat.co.uk/p5sagit/Distar)
+
+Git browser: [http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit/Distar.git;a=summary](http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit/Distar.git;a=summary)
+
+# AUTHOR
+
+mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
+
+# CONTRIBUTORS
+
+haarg - Graham Knop (cpan:HAARG) <haarg@cpan.org>
+
+ether - Karen Etheridge (cpan:ETHER) <ether@cpan.org>
+
+frew - Arthur Axel "fREW" Schmidt (cpan:FREW) <frioux@gmail.com>
+
+Mithaldu - Christian Walde (cpan:MITHALDU) <walde.christian@googlemail.com>
+
+# COPYRIGHT
+
+Copyright (c) 2011-2015 the Distar ["AUTHOR"](#author) and ["CONTRIBUTORS"](#contributors)
+as listed above.
+
+# LICENSE
+
+This library is free software and may be distributed under the same terms
+as perl itself. See [http://dev.perl.org/licenses/](http://dev.perl.org/licenses/).
projects / p5sagit/Distar.git / commitdiff