From: Graham Knop Date: Thu, 16 Apr 2020 07:58:55 +0000 (+0200) Subject: add a readme usable by github X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit%2FDistar.git;a=commitdiff_plain;h=054577ba557db80d2b30123fb474e53903ea11f0 add a readme usable by github GitHub used to be able to read pod documentation from a symlink, even if the target file is a different type. This has been broken for a while (https://github.com/github/markup/issues/1253) so remove the symlink and add a generated README.md file. --- diff --git a/README.md b/README.md new file mode 100644 index 0000000..6d5c0b0 --- /dev/null +++ b/README.md @@ -0,0 +1,208 @@ +# 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 '; + + 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) + +# CONTRIBUTORS + +haarg - Graham Knop (cpan:HAARG) + +ether - Karen Etheridge (cpan:ETHER) + +frew - Arthur Axel "fREW" Schmidt (cpan:FREW) + +Mithaldu - Christian Walde (cpan:MITHALDU) + +# 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/). diff --git a/README.pod b/README.pod deleted file mode 120000 index 4c8cee8..0000000 --- a/README.pod +++ /dev/null @@ -1 +0,0 @@ -lib/Distar.pm \ No newline at end of file