NAME

       Minilla::Tutorial - Tutorial document for Minilla

The Minilla workflow

   Installing
           > cpanm --with-recommends Minilla

       You can install Minilla from CPAN.

       Unlike dzil, you don't need to do any setup. Minilla aggregates user name and e-mail
       address from your "~/.gitconfig" (You already set, isn't it?)

   Making new distribution
       Now it's time to make a new distribution.

           > minil new Dist-Name
           > cd Dist-Name/

       At this point, you will have a really simple Dist-Name directory that contains your module
       file with as minimum boilerplate as possible.

       minil done "git init" and "git add .". You need to commit it ASAP.

           > git commit -m 'initial import'

       Now start writing your code, edit the docs, tests and manage CPAN dependencies with
       cpanfile.

           > $EDITOR lib/Dist/Name.pm t/dist-name.t cpanfile

   Making the first release
       When you get confident and it's about time to ship to CPAN, use the test and release
       command. Before doing so, make sure your git directory is not dirty i.e. all changes are
       committed.

           > git commit -a -m "Done initial version"

       Minilla assumes you have a git remote setup so that you can push all your changes to. I
       recommend you to use either hub gem or App::ph to create a new github repository.

           # Use hub rubygem
           > hub create

           # Use App::ph
           > ph import

       Alternatively, if you prefer to use GitLab you can create a project in their web interface
       and follow the instructions it provides to Push an existing Git repository.

       Now, make sure you have Changes file ready and have a new entry under "{{$NEXT}}", which
       will be expanded to the next version of your module.

           > $EDITOR Changes
           > minil test

       Before you proceed to release step, please ensure the "~/.pause" file is configured
       correctly because Minilla uses CPAN::Uploader to upload your distribution to CPAN.  You
       can specify the location of PAUSE configuration file on minil.toml if you want to.  See
       "CONFIGURATION" in Minilla for further information.

           > minil release

       And your first release is done. The release is tagged on git and all the changes
       automatically made are committed to git as well.

       If this is your first conversion to Minilla and want to make sure you're not going to mess
       CPAN with a bad archive when something goes wrong, you can run the release command with
       FAKE_RELEASE environment variable. This will run all the other release process, except the
       UploadToCPAN step.

           > FAKE_RELEASE=1 minil release

       Wait for PAUSE processing it and your module showing up on MetaCPAN in a few minutes.
       Congratulations!

   Making a maintenance release
       You have new features, bugs, pull requests and get ready to make a next version of your
       module. Great, making a new release is equally easy.

       First, make sure all your code has been committed to git and there's no dirty files in the
       working directory.

       Then make sure to edit Changes file and contain entries for the next release under
       "{{$NEXT}}". You don't need to commit the change to the Changes file, yet.

       Now, make a release!

           > minil test
           > minil release

       The release command will automatically bump the version for you - if you have 0.10, the
       next version will be 0.11 by default, but you will be prompted to confirm that version in
       case you need a major bump.

       You can annotate any lines for which you would like the automatic version bump to be
       skipped by appending, `# No BumpVersion`.

       This will update "Changes", "META.json" and bump $VERSION in your main module. These
       changes made by Minilla will be automatically committed, tagged and pushed to the remote.

MIGRATING

       This section describes how to migrate your current authoring process to Minilla.

   Migrate by "minil migrate"
       You just type "minil migrate".

       It can migrate your distribution automatically. If you can't do it, please report to
       Github issues <https://github.com/tokuhirom/Minilla/issues>.

   Manually migrating from other build tools
       Module Dependencies to cpanfile

       First, move the prereq declaration from Makefile.PL or Build.PL to cpanfile.

       The easiest way to convert existing dependencies to cpanfile is to use the command line
       tool mymeta-cpanfile, which is installed with Module::CPANfile. Run the configuration with
       Makefile.PL for the one last time, then run the mymeta-cpanfile command:

           > perl Makefile.PL
           > mymeta-cpanfile --no-configure
           requires 'DBI', '1.000';

           on test => sub {
               requires 'Test::More', '0.86';
           }

           ...

       You can redirect the output to cpanfile if you like. It is important to pass
       --no-configure option here, since otherwise modules like ExtUtils::MakeMaker will be
       included. It is not required with Minilla setup, since Minilla knows which configuration
       tool (installer) to use and include them in META files upon the releases. You can leave
       that out from the cpanfile.

       If you decide to manually construct new cpanfile, the format is mostly compatible to
       Module::Install's requirement DSL.

           # Makefile.PL
           test_requires 'Test::More', 0.90;
           requires 'Plack', '1.000';

       becomes:

           # cpanfile
           test_requires 'Test::More', 0.90;
           requires 'Plack', '1.000';

       which is exactly the same. If you use Module::Build or ExtUtils::MakeMaker, that will be
       more manual process, but basically the same thing. See cpanfile for the available syntax.

       Remove boilerplate

       Next, remove unnecessary boilerplate files.

           > git rm {Makefile,Build}.PL MANIFEST MANIFEST.SKIP README .shipit

       Edit configurations

       Edit .gitignore and add the following lines:

           /Dist-Name-*
           /.build
           !META.json

       You're almost done, and your directory will look like:

           cpanfile
           lib/Dist/Name.pm
           t/...

       "git add" the newly created files and commit it.

       Make a new build

       Now you're ready to make the first build.

           > minil build

       and if it was successful, you get a build in a directory called "Dist-Name-v0.1.0" under
       your current directory. They can be later removed with "minil clean" command.

       Also, new "Build.PL", "META.json" and "README.md" are added in your working directory for
       git-friendliness. "git add" them and commit it.

          > git add Build.PL META.json README.md && git commit -m "git stuff"

       Now you're ready to roll a new release with Minilla. Before doing so, convert your
       "Changes" file format a little bit, and make sure you have a following header in the top:

         {{$NEXT}}

           - Change log entry for the next version

       The "{{$NEXT}}" is a template variable that gets replaced with the version and date
       string, when you make a next release. This is almost the only change you're required to
       make in your code base.

       Now, run the release command:

           > minil release

       to make a new release, in the same way described above for a new Minilla setup. You can
       set "FAKE_RELEASE" environment variable if this is your first conversion and want to
       double check what happens, before uploading to CPAN.

       When this is not your first release, the version number gets automatically bumped by
       Minilla, but you will be prompted if that is exactly the version you want, and if you want
       a major version up, you can specify to do so.

AUTHOR

       Tokuhiro Matsuno

       Tatsuhiko Miyagawa (Most of documents are taken from Dist::Milla::Tutorial!)

SEE ALSO

       Minilla, Dist::Milla::Tutorial