Bug #125177 for Fey: Instructions in CONTRIBUTING.md confusing

Sun Apr 22 09:19:08 2018 jkeenan [...] cpan.org - Ticket created

Subject:

Instructions in CONTRIBUTING.md confusing

Today I attempted to clone Fey and work with it locally in order to address ___ and ___. To my dismay, I found no ```Makefile.PL``` or ```Build.PL``` in the repository. I groaned, thinking, "This means a big download from CPAN in order to work with ```dzil```." Dist::Zilla: the way CPAN authors make life miserable for people exploring unexpected breakages! First, that meant that I had to work my way through ```CONTRIBUTING.md```. I found it to be very confusing, in part because it mixes instructions relevant to use of ```cpan``` with those relevant to ```cpanm```. Because on the machine where I wanted to work I use ```cpanm```, I settled on this: ``` dzil listdeps --author --missing | cpanm ``` 72 module installations later, I figured I'd be good to go. I called ```dzil build``` and got reasonable output: ``` $ dzil build [@DROLSKY/Dist::Zilla::PluginBundle::DROLSKY] checking for stale modules... [DZ] beginning to build Fey [DZ] guessing dist's main_module is lib/Fey.pm [@DROLSKY/GitHub::Meta] Getting GitHub repository info [DZ] writing Fey in Fey-0.44 [@DROLSKY/CopyFilesFromBuild] Copied Fey-0.44/CONTRIBUTING.md to CONTRIBUTING.md [@DROLSKY/CopyFilesFromBuild] Copied Fey-0.44/LICENSE to LICENSE [@DROLSKY/CopyFilesFromBuild] Copied Fey-0.44/README.md to README.md [@DROLSKY/CopyFilesFromBuild] Copied Fey-0.44/cpanfile to cpanfile [@DROLSKY/CopyFilesFromBuild] Copied Fey-0.44/Makefile.PL to Makefile.PL [DZ] building archive with Archive::Tar; install Archive::Tar::Wrapper 0.15 or newer for improved speed [DZ] writing archive to Fey-0.44.tar.gz [DZ] built in Fey-0.44 ``` On to ```dzil test```! Here things fell apart. Here's just an excerpt from the error output: ``` Warning: prerequisite DateTime::Format::MySQL 0 not found. Warning: prerequisite Fey::Test 0.05 not found. Warning: prerequisite List::AllUtils 0 not found. Warning: prerequisite MooseX::SemiAffordanceAccessor 0.03 not found. Warning: prerequisite MooseX::StrictConstructor 0.13 not found. ``` With, needless to say, massive test failures: ``` Result: FAIL Failed 29/32 test programs. 1/5 subtests failed. Makefile:956: recipe for target 'test_dynamic' failed make: *** [test_dynamic] Error 2 error running make test ``` Now, generally speaking, I know how to follow instructions. But if these are the results I got, then I think it's safe to conclude that the instructions are confusing. Thank you very much. Jim Keenan

Sun Apr 22 09:20:13 2018 jkeenan [...] cpan.org - Correspondence added

On Sun Apr 22 09:19:08 2018, JKEENAN wrote: Show quoted text

> Today I attempted to clone Fey and work with it locally in order to > address ___ and ___. >

Meant to fill in those blanks before posting: https://rt.cpan.org/Ticket/Display.html?id=125168 https://rt.perl.org/Ticket/Display.html?id=133139 Show quoted text

> To my dismay, I found no ```Makefile.PL``` or ```Build.PL``` in the > repository. I groaned, thinking, "This means a big download from CPAN > in order to work with ```dzil```." > > Dist::Zilla: the way CPAN authors make life miserable for people > exploring unexpected breakages! > > First, that meant that I had to work my way through > ```CONTRIBUTING.md```. I found it to be very confusing, in part > because it mixes instructions relevant to use of ```cpan``` with those > relevant to ```cpanm```. Because on the machine where I wanted to > work I use ```cpanm```, I settled on this: > ``` > dzil listdeps --author --missing | cpanm > ``` > 72 module installations later, I figured I'd be good to go. I called > ```dzil build``` and got reasonable output: > ``` > $ dzil build > [@DROLSKY/Dist::Zilla::PluginBundle::DROLSKY] checking for stale > modules... > [DZ] beginning to build Fey > [DZ] guessing dist's main_module is lib/Fey.pm > [@DROLSKY/GitHub::Meta] Getting GitHub repository info > [DZ] writing Fey in Fey-0.44 > [@DROLSKY/CopyFilesFromBuild] Copied Fey-0.44/CONTRIBUTING.md to > CONTRIBUTING.md > [@DROLSKY/CopyFilesFromBuild] Copied Fey-0.44/LICENSE to LICENSE > [@DROLSKY/CopyFilesFromBuild] Copied Fey-0.44/README.md to README.md > [@DROLSKY/CopyFilesFromBuild] Copied Fey-0.44/cpanfile to cpanfile > [@DROLSKY/CopyFilesFromBuild] Copied Fey-0.44/Makefile.PL to > Makefile.PL > [DZ] building archive with Archive::Tar; install Archive::Tar::Wrapper > 0.15 or newer for improved speed > [DZ] writing archive to Fey-0.44.tar.gz > [DZ] built in Fey-0.44 > ``` > On to ```dzil test```! Here things fell apart. Here's just an > excerpt from the error output: > ``` > Warning: prerequisite DateTime::Format::MySQL 0 not found. > Warning: prerequisite Fey::Test 0.05 not found. > Warning: prerequisite List::AllUtils 0 not found. > Warning: prerequisite MooseX::SemiAffordanceAccessor 0.03 not found. > Warning: prerequisite MooseX::StrictConstructor 0.13 not found. > ``` > With, needless to say, massive test failures: > ``` > Result: FAIL > Failed 29/32 test programs. 1/5 subtests failed. > Makefile:956: recipe for target 'test_dynamic' failed > make: *** [test_dynamic] Error 2 > error running make test > ``` > Now, generally speaking, I know how to follow instructions. But if > these are the results I got, then I think it's safe to conclude that > the instructions are confusing. > > Thank you very much. > Jim Keenan

Wed Apr 25 14:15:36 2018 ether [...] cpan.org - Correspondence added

On 2018-04-22 06:19:08, JKEENAN wrote: Show quoted text

> Today I attempted to clone Fey and work with it locally in order to > address ___ and ___. > > To my dismay, I found no ```Makefile.PL``` or ```Build.PL``` in the > repository. I groaned, thinking, "This means a big download from CPAN > in order to work with ```dzil```." > > Dist::Zilla: the way CPAN authors make life miserable for people > exploring unexpected breakages!

Unless the distribution contains XS, or other complicated magic, it should be perfectly sufficient to simply run 'prove -lr t' to run tests, after satisfying prerequisites.

Wed Apr 25 14:15:37 2018 The RT System itself - Status changed from 'new' to 'open'