G'day Alex,

I use Module::Starter with Module::Starter::PBP as a plugin. I use that plugin mainly because I like the templates which I customise a lot (I also pull out the PBP specific parts, e.g. perlcritic.t).

I keep a number of config files for various purposes; e.g. OO mod, functional mod, $work mod, etc. Each of these points to a different directory with my customised templates. Here's the current one:

$ cat ~/.module-starter/config
author:  Ken Cotterill
email:   kcott@cpan.org
builder: ExtUtils::MakeMaker
plugins: Module::Starter::PBP
template_dir: /home/ken/.module-starter/P532

$ ls -al ~/.module-starter/P532
total 24
drwxr-xr-x+ 1 ken None    0 Jan  9  2021 .
drwxr-xr-x+ 1 ken None    0 Jan  6  2021 ..
-rw-r--r--  1 ken None   89 Jan  5  2021 Changes
-rw-r--r--  1 ken None  586 Jan  5  2021 Makefile.PL
-rw-r--r--  1 ken None   82 Jan  9  2021 MANIFEST.SKIP
-rw-r--r--  1 ken None 5205 Jan  5  2021 Module.pm
-rw-r--r--  1 ken None  313 Dec 19  2020 README
drwxr-xr-x+ 1 ken None    0 Jan  9  2021 t
[download]

And, just to give you an idea of the templates, Module.pm has:

package <MODULE NAME>;
...
=head1 LICENCE AND COPYRIGHT

Copyright (c) <YEAR>, <AUTHOR> C<< <<EMAIL>> >>. All rights reserved.
...
[download]

Creating the module is a little easier with this plugin because you don't need to specify so many options (e.g. the --author="Andy Lester" --email=andy@petdance.com, or equivalent, are not required).

Creating the distribution uses the fairly standard incantation:

perl Makefile.PL
make
make test
make dist
[download]

That last command creates the distribution tarball.

I'd generally want to also run Author Tests so something like this first (your environment variable may have a different name):

$ export RELEASE_TESTING=1
[download]

I've used this method dozens (if not hundreds) of times and not encountered problems: it seems robust and stable.

Suggestions about what the heck's going on will be gratefully received.

I concur with kcott and Discipulus. For your first release to CPAN don't even think about using one of the release automation tools like Minilla or Dist::Zilla, etc. They are fine for people who do a lot of releases and already fully understand the procedure but for a first-timer they will be confusing at best.

Follow the guides such as How to make a CPAN Module Distribution and just use the simple, basic tools many of which are in Core. Once you have a tarball ready for upload to CPAN, I strongly suggest that you copy it to a fresh machine and try to upack it and install your module there first. This can catch any number of problems before you upload it to CPAN.

Thanks for considering releasing your code and good luck with the release.

I actually used Dist::Zilla for my very first module (in 2013, when Dist::Zilla was already fairly refined) and I remember there being a learning curve, but I was having just as much learning curve trying to figure out the other tools. In the end I went with Dist::Zilla because I hate having package boilerplate hanging around in my git repository, and because I can't ever remember to do all the manual steps during a release like updating all the version numbers in each module and updating the Manifest and tagging in git, etc.

You, sir, are a trooper and I take my hat off to you.

I, along with some other denizens of these halls, participated in the Pull Request Challenge a few years back and when it so happened that the module I was assigned required Dist::Zilla my heart would sink. Such an overblown, unnecessary framework - complex and heavy in equal measure - which for a single run-and-release gives back very little. I can fully understand why folks like RJBS and perlancar would use it but it is not for me.

because I can't ever remember to do all the manual steps during a release like updating all the version numbers in each module and updating the Manifest and tagging in git, etc.

I wrote a script which does that for me. It is entirely unnecessary for anyone else to have that script or know that it exists. This means that they can collaborate with me on my modules in GitLab (or elsewhere) without having to use either my script or Dist::Zilla or anything else. It is no barrier to participation.

---

🦛

Thanks for pointing out the link to the guide -- I originally skipped it, as one of the references said, Oh that uses h2xs, that's ancient. After looking at the guide a little more closely this morning, it looks like it has everything I need to more or less do the needful. I appreciate your feedback, and I'll try this out tonight after work. :)

Alex / talexb / Toronto

Thanks PJ. We owe you so much. Groklaw -- RIP -- 2003 to 2013.

I still use h2xs for pure Perl modules - think I probably need to update that. Is this still state of the art for XS starters?

I also noted in Minilla, assumes among other things:

> Your modules are written in Pure Perl and are located in lib/.

> but that module doesn't have anything about packaging up my code..

as side comment you dont need an external tool to just pack the module: perl Makefile.PL then make dist will do the job. See the relevant part of my little guide

L*

The DBD::CSV module presumably lets you access a CSV file using the DBI module. I wanted to use a tool that's more command line oriented. And then I decided, I'm not going to go look for it, I'll just build it.

Alex / talexb / Toronto

Thanks PJ. We owe you so much. Groklaw -- RIP -- 2003 to 2013.

I just want to package up the *existing* version.

Your next stable version in this case would be 0.01.

Ugh .. so what minil is asking is "What version are we building today? (As in, what's the next version that's going to get uploaded to CPAN?)" At the end of a long day, this is not the kind of mental gymnastics I am able to comprehend.

OK -- thanks for that. I entered 0.01 this time, and looked fine until .. it failed in exactly the same way. My repo is here: https://github.com/talexb/CSVDB.

Alex / talexb / Toronto

Thanks PJ. We owe you so much. Groklaw -- RIP -- 2003 to 2013.

Well, on my system, this is the test results:

t/20-cmdline.t              (Wstat: 11520 Tests: 50 Failed: 45)
  Failed tests:  2-10, 12-20, 22-30, 32-40, 42-50
  Non-zero exit status: 45
t/21-cmdline.t              (Wstat: 4608 Tests: 20 Failed: 18)
  Failed tests:  2-10, 12-20
  Non-zero exit status: 18
t/22-cmdline.t              (Wstat: 17664 Tests: 77 Failed: 69)
  Failed tests:  2-5, 7-12, 14, 16-21, 23-32, 34-45, 47-60
                62-77
  Non-zero exit status: 69
xt/boilerplate.t            (Wstat: 0 Tests: 3 Failed: 0)
  TODO passed:   1, 3
xt/minilla/spelling.t       (Wstat: 256 Tests: 1 Failed: 1)
  Failed test:  1
  Non-zero exit status: 1
[download]

You're still missing a LICENSE file but your cpanfile should look like this:

requires 'perl' => 5.8.1;
requires 'Text::CSV' => 0;
[download]

Minilla comes with the functionality to create new dists with minil new [project here]. It'll lay everything out including your cpanfile, LICENSE, minil.toml etc.

When I was creating Business::Stripe::WebCheckout, this information from eyepopslikeamosquito was invaluable and worthy was regular re-reading. It may help you...

Re: [RFC] Module code and POD for CPAN

Not helpful WRT your problem, but you might check out q (https://harelba.github.io/q/) which is a python (and pandas?) thing which does something similar for features to steal inspiration. Have had some people intermittently use it at $work.

OT^2: The link you provided also contains this interesting reading: Basics of the Unix Philosophy (write programs to write programs when you can., When in doubt, use brute force. etc.)

I like to use #VERSION comments in my files that get replaced by whatever version is being built, default to the next version based on the last git tag, have Git be responsible for the MANIFEST, move all my POD to the __END__ of the file, automatically determine my prereqs but let me override them, and test my code for documentation coverage. You can see a minimal configuration for all of that in my module Log::Progress / dist.ini

Once everything is installed, my release process is "dzil test" then "dzil release", it prompts me for my PAUSE password, then it's published. Releasing a dev version is "V=1.11_01 dzil release" then later "V=1.12 dzil release" to get back to 2 decimal places.

Thanks for the suggestion .. I saw that was one of the alternatives, but I also read the warnings that it was a bit of a battleship, and decided that there must be something a little more lightweight for my tiny module that has one dependency.

Alex / talexb / Toronto

Thanks PJ. We owe you so much. Groklaw -- RIP -- 2003 to 2013.

I agree here. It's really a guilty pleasure because it's so massive, but you only need to install it on your dev machine.

But you raise the bar for anyone willing to come up with a patch.

I've seen not a single project using Dist::Zilla that does not requires (many) additional modules and plugins that won't be used for anything else and thus clutter *my* development box if I want to not only fix something, but also test it before I submit a PR.

Whereever possible, I will stick to ExtUtils::MakeMaker and it has so far never let me down.

And for all those that add scripts: add them to a folder (e.g. sandbox) in your git repo, so people trying to help you have them too. And document them in Makefile.PL or README.

My €0.02

Also read Release::Checklist for motivations.


Enjoy, Have FUN! H.Merijn