Beefy Boxes and Bandwidth Generously Provided by pair Networks
We don't bite newbies here... much
 
PerlMonks  

Re: [RFC] Module code and POD for CPAN

by eyepopslikeamosquito (Archbishop)
on Apr 14, 2021 at 10:49 UTC ( [id://11131258]=note: print w/replies, xml ) Need Help??


in reply to [RFC] Module code and POD for CPAN

Years ago I wrote Writing Solid CPAN Modules and have updated it periodically. It is quite long though and with too many references (which I'm sure you don't have time to read). So I skimmed through it just now to extract an abbreviated "Bod's essential reading list":

I'm rusty on CPAN authorship nowadays, so if I've overlooked other mandatory reading for new CPAN authors (and any other cool CPAN author references you may know of) please let us know.

Replies are listed 'Best First'.
Re^2: [RFC] Module code and POD for CPAN
by Bod (Parson) on Apr 14, 2021 at 22:36 UTC

    OK, so I have followed the instructions and used module-starter to create a package directories. I've them edited Makefile.PL and MANIFEST.

    gmake test revealed an error under Perl v5.32 which didn't show up in v5.16 where I was testing:

    Error: Experimental splice on scalar is now forbidden at C:\Users\use +r\Perl\Business-Stripe-WebCheckout\blib\lib/Business/Stripe/WebChecko +ut.pm line 127, near "1;"
    Now corrected changing this line to explicitly dereference the array:
    splice $self->{'trolley'}, $i, 1; splice @{$self->{'trolley'}}, $i, 1;
    It installs locally with gmake install

    Is this a good test result or do I need to be adding in more tests?

    C:\Users\user\Perl\Business-Stripe-WebCheckout>gmake test "C:\Strawberry\perl\bin\perl.exe" "-MExtUtils::Command::MM" "-MTest::H +arness" "-e" "undef *Test::Harness::Switches; test_harness(0, 'blib\l +ib', 'blib\arch')" t/*.t t/00-load.t ....... 1/? # Testing Business::Stripe::WebCheckout 0.11, +Perl 5.032001, C:\Strawberry\perl\bin\perl.exe t/00-load.t ....... ok t/manifest.t ...... skipped: Author tests not required for installatio +n t/pod-coverage.t .. skipped: Author tests not required for installatio +n t/pod.t ........... skipped: Author tests not required for installatio +n All tests successful. Files=4, Tests=1, 0 wallclock secs ( 0.06 usr + 0.01 sys = 0.08 CPU +) Result: PASS

    But...I am getting an error at the gmake dist stage.

    C:\Users\user\Perl\Business-Stripe-WebCheckout>gmake dist "C:\Strawberry\perl\bin\perl.exe" -MExtUtils::Command -e rm_rf -- Busi +ness-Stripe-WebCheckout-0.1_1 "C:\Strawberry\perl\bin\perl.exe" "-MExtUtils::Manifest=manicopy,manir +ead" \ -e "manicopy(maniread(),'Business-Stripe-WebCheckout-0.1_1', ' +best');" mkdir Business-Stripe-WebCheckout-0.1_1 mkdir Business-Stripe-WebCheckout-0.1_1/t mkdir Business-Stripe-WebCheckout-0.1_1/lib mkdir Business-Stripe-WebCheckout-0.1_1/lib/Business mkdir Business-Stripe-WebCheckout-0.1_1/lib/Business/Stripe Generating META.yml Generating META.json tar cvf Business-Stripe-WebCheckout-0.1_1.tar Business-Stripe-WebCheck +out-0.1_1 a Business-Stripe-WebCheckout-0.1_1 a Business-Stripe-WebCheckout-0.1_1/Changes a Business-Stripe-WebCheckout-0.1_1/lib a Business-Stripe-WebCheckout-0.1_1/LICENSE a Business-Stripe-WebCheckout-0.1_1/Makefile.PL a Business-Stripe-WebCheckout-0.1_1/MANIFEST a Business-Stripe-WebCheckout-0.1_1/META.json a Business-Stripe-WebCheckout-0.1_1/META.yml a Business-Stripe-WebCheckout-0.1_1/README a Business-Stripe-WebCheckout-0.1_1/t a Business-Stripe-WebCheckout-0.1_1/t/00-load.t a Business-Stripe-WebCheckout-0.1_1/t/manifest.t a Business-Stripe-WebCheckout-0.1_1/t/pod-coverage.t a Business-Stripe-WebCheckout-0.1_1/t/pod.t a Business-Stripe-WebCheckout-0.1_1/lib/Business a Business-Stripe-WebCheckout-0.1_1/lib/Business/Stripe a Business-Stripe-WebCheckout-0.1_1/lib/Business/Stripe/WebCheckout.pm "C:\Strawberry\perl\bin\perl.exe" -MExtUtils::Command -e rm_rf -- Busi +ness-Stripe-WebCheckout-0.1_1 gzip -9f Business-Stripe-WebCheckout-0.1_1.tar process_begin: CreateProcess(NULL, gzip -9f Business-Stripe-WebCheckou +t-0.1_1.tar, ...) failed. make (e=2): The system cannot find the file specified. gmake: *** [Makefile:612: Business-Stripe-WebCheckout-0.1_1.tar.gz] Er +ror 2
    I've check the tar file and everything appears to be in there so I take it the error is packing the tar file into a .gz archive. But I'm not sure what to try next...

      Is this a good test result or do I need to be adding in more tests?

      Both! It is good in that the stock tests pass but they are only testing for very basic things - have a read of t/00-load.t to see how little it actually does. What you should do next is write your own tests which actually test your code to show that it does what it is supposed to do and that it handles edge cases as intended, etc.

      Also, the skipped: Author tests not required for installation is great for end users but not for you as author. You want to run those yourself so be sure to set the AUTHOR_TESTING environment variable to get them to run for you.


      🦛

        The documentation has now been updated taking into consideration all the feedback people have kindly provided.

        I've gone through the documentation and written several tests for each method. Some time ago I read an article about writing tests and cannot find it now. But the one thing that stood out from it was to start writing tests based on the documentation...so that is about what I have done. However, I cannot see a way to test getting an intent as that requires a valid API key. Something that will not be available to the installation scripts. So I have called the method and checked that the success method returns false. Is there a better way to handle the lack of API key?

        This has generated some more questions:

        There are 30 tests I have created but gmake test says there are 31. Does diag count as a test or does something else account for the discrepancy?

        If plan tests => 31 is included I get the error Parse errors: Plan (1..31) must be at the beginning or end of the TAP output. However, plan tests => 31 was autogenerated. I have to use Test::More tests => 31; to get rid of the error. I cannot find any explanation of the error so what does it actually mean?

        Are there any other glaringly obvious tests that should be included, but that have been left out?

        00-load.t

        Also just to note in case anyone else finds this in future - the environment variable (on Strawberry Perl at least) is RELEASE_TESTING and not AUTHOR_TESTING

Re^2: [RFC] Module code and POD for CPAN
by Bod (Parson) on Apr 14, 2021 at 11:18 UTC

    Fabulous...thank you 😊

    I shall do some more reading later today. As it is Weekend Wednesday and the sun is shining, outside is calling first...

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://11131258]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others chanting in the Monastery: (4)
As of 2024-04-19 14:50 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found