Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Minilla::Tutorial(3)  User Contributed Perl Documentation Minilla::Tutorial(3)

NAME
       Minilla::Tutorial - Tutorial document for Minilla

The Minilla workflow
   Installing
	   > cpanm Minilla

       You can install Minilla from CPAN.

       Unlike dzil, you	don't need to 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

       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

perl v5.32.1			  2018-02-20		  Minilla::Tutorial(3)

NAME | The Minilla workflow | MIGRATING | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Minilla::Tutorial&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help