How do I package a module and related apps for successful upload to cpan

PUCKERING has asked for the wisdom of the Perl Monks concerning the following question:

I'm having trouble uploading a Dist::Zilla distro to PAUSE using the name GHCN. The email I received says:

"This distribution name will only be indexed when uploaded by users with permission for the package GHCN. Either someone else has ownership over that package name, or this is a brand new distribution and that package name was neither listed in the 'provides' field in the META file nor found inside the distribution's modules. Therefore, no modules will be indexed."

What I'm uploading is a tarball build with Dist::Zilla and which contains a collection of modules that are for building applications that access the NOAA Global Climatology Network data repository. I've named these modules GHCN::Station, GHCN::StationTable etc. There is no GHCN.pm module. There is no existing entry for GHCN in cpan.

I've also developed several application scripts for general use that are based on the GHCN modules. They exist as .pl scripts in the distro bin directory that invoke a run() subroutine within corresponding modules in the lib/App directory. For example, the script ghcn_fetch.pl is really just a thin wrapper around App::GHCH::Fetch, which in turn uses the GHCN:: modules noted earlier.

My objective is to have:

1. A single cpan entry GHCN which lists all the GHCN:: modules

2. A single cpan entry for App::GHCN which lists App::GHCN::Fetch, App::GHCN::Extremes and App::GHCN::StationCounts

3. cpan entries for ghcn_fetch.pl, ghcn_extremes.pl and ghcn_station_counts.pl

Maybe this is a tall order. Maybe I need one distro for the GHCN modules (but what to name it?) and other distros for the apps.

So far I've tried name = GHCN and name = bin/ghcn_fetch.pl, but both of those generate a permission error (see message noted above).

I could try name = App-GHCN-Fetch, but every failed attempt further pollutes the namespace, so I'd like to have some idea of how to do this correctly before adding more deadwood. Another possibility is name = GHCN-StationTable since it is the most important class of the collection -- the one that does all the heavy lifting.

I had a look at a few projects that had modules and apps, but there didn't seem to be a consistent way to do things, or any documentation for Dist::Zilla explaining how to structure and name a distribution like this.

And speaking of documentation, my .pl scripts, which I said reside under bin are listed as Documentation! Why? See https://metacpan.org/release/PUCKERING/GHCN-v0.22.258

Any suggestions for structuring this project and specifying it in dist.ini so that I can get a reasonable deployment of the modules and the accompanying apps would be appreciated.

Comment on How do I package a module and related apps for successful upload to cpan

Replies are listed 'Best First'.
Re: How do I package a module and related apps for successful upload to cpan by hippo (Bishop) on Sep 15, 2022 at 10:04 UTC
a collection of modules that are for building applications that access the NOAA Global Climatology Network data repository. I've named these modules GHCN::Station, GHCN::StationTable etc. Forgive me, but that seems to be a rather specific use case. Why is it that you think this deserves its own top-level namespace? Wouldn't these fit under WebService:: or somewhere like that? Did you discuss the name here first? ~~On or PrePAN?~~ Or on module-authors@perl.org? my .pl scripts, which I said reside under bin are listed as Documentation! Why? Perhaps because scripts like this are usually placed in `scripts/` as opposed to `bin/`? To answer the question in the title, you should indeed split the dist into 2. People who want to use the webservice/protocol side of it won't necessarily want the application. So, distribute the webservice integration as one dist and the application as a second dist which has the first as a dependency. While you're in there making such changes, it would be better to omit the dist.ini from the uploaded tarball(s). Edit: Gah! PrePAN appears to have gone and been snaffled by a domain grabber. Another one bites the dust. 🦛	[reply] [d/l] [select]
Re^2: How do I package a module and related apps for successful upload to cpan by PUCKERING (Sexton) on Sep 15, 2022 at 13:49 UTC
Thanks for your insight. I hadn’t really thought through the implications of creating a new top level namespace. The thing is, we can upload pretty much any standalone module we want so long as the name is unique. And I picked a pretty unique name to contain my related modules. It didn’t occur to me the rules would be different for a namespace, though it makes sense that they are. I’ll try to find something suitable. I’ll try /scripts. I had read that /scripts and /bin were supported in Dist:Zilla, it I don’t recall there being any clear distinction made and I was following other examples on cpan where /bin is used, like App::cpanminus. I’ll omit dist.ini from the tarball. I thought I had done that, so thanks for the catch.	[reply]
Re^3: How do I package a module and related apps for successful upload to cpan by hippo (Bishop) on Sep 15, 2022 at 15:58 UTC
I’ll try /scripts. I had read that /scripts and /bin were supported in Dist:Zilla, it I don’t recall there being any clear distinction made and I was following other examples on cpan where /bin is used, like App::cpanminus. If you take a look at how MetaCPAN treats the file in `bin/` in App::cpanminus you will notice that it too is labelled as "Documentation". Arguably, it shouldn't be but if you put your scripts in `scripts/` like HTML::Template then they evidently won't be considered as documentation. It's a very minor point, all told. Edited for link typo (Thanks, pryrt) 🦛	[reply] [d/l] [select]
Re^4: How do I package a module and related apps for successful upload to cpan by PUCKERING (Sexton) on Sep 15, 2022 at 17:17 UTC
Re^5: How do I package a module and related apps for successful upload to cpan by PUCKERING (Sexton) on Sep 15, 2022 at 17:37 UTC
Re^3: How do I package a module and related apps for successful upload to cpan by eyepopslikeamosquito (Archbishop) on Sep 15, 2022 at 21:35 UTC
> I’ll try /scripts. I had read that /scripts and /bin were supported in Dist:Zilla ... Note that davido, in Re: What do I use to release a module to CPAN for the first time?, strongly advises you to stay away from Dist::Zilla until you understand every step involved in doing it manually: If you were using Dist::Zilla (which you shouldn't be using for your first module, or maybe even your first ten modules)... Based on your experiences, davido's advice seems to be spot on. :)	[reply]
Re: How do I package a module and related apps for successful upload to cpan by eyepopslikeamosquito (Archbishop) on Sep 15, 2022 at 12:32 UTC
hippo has already given some excellent advice. Sadly, the Pause Module List is no longer maintained and PrePAN has vanished. I hope the BioPerl folks and other members of the Perl scientific community are listening and provide advice to your question here. See the "Choosing a Module Name" section at Writing Solid CPAN Modules for some general advice on CPAN module naming. The trickiest problem you face is choosing the appropriate top-level namespace. Going through Pause Module List, nothing jumped out at me, but I noticed there is no "Climatology" top-level namespace. Given that `genealogy` exists as a top-level namespace, I don't see that `climatology` is any less obscure. :) I'm not sure of the mechanism nowadays for creating a new top-level namespace and whether `climatology` would be allowed. Of the existing top-level namespaces `webservice` and `weather` seemed the closest to me.	[reply] [d/l] [select]
Re^2: How do I package a module and related apps for successful upload to cpan by PUCKERING (Sexton) on Sep 15, 2022 at 13:55 UTC
Thanks for the advice and the links. Funny thing is I never even considered bundling these modules under “Weather”, but that does seem like a suitable top level namespace. There’s even a Weather::NOAA sub space that would also be a suitable place for ::GHCN::	[reply]
Re: How do I package a module and related apps for successful upload to cpan by eyepopslikeamosquito (Archbishop) on Sep 17, 2022 at 05:01 UTC
In case it's of use or interest, a random search of CPAN just now found these distributions: Weather::NOAA::GFS by Lorenzo Becchi (2005) - Perl module for forecast weather maps from NOAA GFS site data Weather::NOAA::Alert by Michael Stovenour (2011) - Polling and parsing of NOAA CAP 1.1 Alerts Weather::GHCN::Fetch by Gary Puckering (2022) - Access the NOAA GHCN Global Historical Climatology Network repository (new author, probably not worth looking at ;-) Geo::WeatherNOAA by Mark Solomon (2006) - Perl extension for interpreting the NOAA weather data Geo::METAR by Koos van den Hout (2008) - Process aviation weather reports in the METAR format Geo::WeatherNWS by Bob Ernst (2018) - A simple way to get current weather data from the NWS Bot::BasicBot::Pluggable::Module::Weather by Simon Wistow (2005) - Get the weather forecast from NOAA Ham::NOAA::Sunspot by Roger Pettett (2017) - Process sunspot prediction data from NOAA FTP/Website Googling found this background reference on GHCN: Dive into the Global Historical Climatology Network data using Perl and SQL by A. Sinan Unur. See also: National Oceanic and Atmospheric Administration (NOAA) and NOAA Global Historical Climatology Network Daily (GHCN-D).	[reply]
Re^2: How do I package a module and related apps for successful upload to cpan by PUCKERING (Sexton) on Sep 17, 2022 at 17:40 UTC
Yes, after your advice I found those too. I decided to repackage my collection under Weather -- but not Weather::NOAA simply because the code there is defunct and the author unreachable. Weather::GHCN::Fetch is my new package name. A quick look at Geo::WeatherNOAA says it's for grabbing forecasts from www.weather.gov. Looks like it once accessed http://iwin.nws.noaa.gov/iwin/ but not any more. The url nws.noaa.gov is still ping-able, but doesn't return any response. Weather:: seems like a better place for that module (if it even works) and it shouldn't have NOAA in the name. CPAN has some cruft, that's for sure. Is there a process for cleanup?	[reply]
Re^3: How do I package a module and related apps for successful upload to cpan (CPAN and Github References) by eyepopslikeamosquito (Archbishop) on Sep 17, 2022 at 23:11 UTC
CPAN has some cruft, that's for sure. Is there a process for cleanup? This is a problem faced by all open repositories with a low barrier to entry, such as Python Package Index, RubyGems, GitHub ... even Perl Monks (which has an infamous zombification process - including an option to raise from the dead :). To encourage authors to cleanup their old cruft on CPAN, Perl has The BackPAN (a complete history of CPAN) from which nothing is ever deleted. Curating CPAN References Curating Old Releases by neilb (2015) Curating CPAN sometimes means really deleting stuff by BooK (2014) "Curating CPAN" section at Writing Solid CPAN Modules Github References Re^4: testing/release advice [was: Stopping tests] by stevieb (2023) - use Github Actions to perform automated CI testing on every push to the repo RFC: Continuous Integration (CI) for your CPAN modules (for free!) by stevieb (2016) - CI with Github, Travis-CI, Coveralls, CPAN, Devel::Cover (reply mentions cpancover) Updated: Added Curating CPAN References and Github References sections.	[reply]
Re: How do I package a module and related apps for successful upload to cpan by PUCKERING (Sexton) on Sep 17, 2022 at 17:50 UTC
Update: After some trial and error I discovered the root problem. I was trying to publish a distro whose name GHCN did not correspond to a module in the package; i.e. there was no GHCN.pm. In hindsight the answer was in the PAUSE message. Either someone else has ownership over that package name, or this is a brand new distribution and that package name was neither listed in the 'provides' field in the META file nor found inside the distribution's modules. Obvious now, wasn't then. I was thinking of GHCN:: as a container for modules, but GHCN was not a sensible choice for the main entry point. Once I figured that out, I decided that Fetch.pm would make a good entry point, and based on the other feedback I received here I decided to name the collection Weather::GHCN::Fetch. Thanks again for your advice. It was most helpful.	[reply]
Re^2: How do I package a module and related apps for successful upload to cpan by NERDVANA (Deacon) on Sep 19, 2022 at 10:43 UTC
While I agree that top-level GHCN was a bad idea, if it had been an appropriate name, you can always make a GHCN.pm which contains nothing but POD explaining the collection of modules. Or, create a top level module that does nothing but export sugar functions for working with the other objects in the collection.	[reply]


more useful options
	PerlMonks