Skip Menu |

Preferred bug tracker

Please visit the preferred bug tracker to report your issue.

This queue is for tickets about the Dist-Zilla CPAN distribution.

Report information
The Basics
Id: 63786
Status: resolved
Priority: 0/
Queue: Dist-Zilla

People
Owner: Nobody in particular
Requestors: KENTNL [...] cpan.org
Cc:
AdminCc:

Bug Information
Severity: Important
Broken in: 4.102345
Fixed in: (no value)



Subject: Suggested Docs improvement for new-dist.html
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
10:44:48 < kentnl> rjbs: feedback from <Altreus> on freenode re: http://dzil.org/tutorial/new-dist.html , what the [@Basic] does is unobvious and you don't even realise you need to know what goes on
                   inside it, and when things go wrong ( Such as a duplicate file with README ) they don't nessecarily get "why"
10:45:09 < rjbs> duplicate files should really be clear.
10:45:20 < rjbs> I will look at that page again, though.
10:45:24 < rjbs> RT tickets == great reminders.
10:45:39 < kentnl> it is written there, but its like in the writing under the code sample under the other code sample
10:46:49 < kentnl> I'd suggest some sort of code-comment such as [@Basic] # Load a list of plugins specified by Dist::Zilla::PluginBundle::Basic 
10:47:45 < kentnl> ( like I said, it *is* all there, but it makes sense the way its written only from the perspective of somebody who's been there )
10:47:58 < rjbs> nod
10:48:32 < kentnl> I'd even possibly expand In that page what [@Basic] does, because really, it does *everything*
10:50:46  * kentnl files an rt

Points in this discussion appear to have been deemed useful by the recipient.

10:09:55 < Altreus> kent\n: dzil says this when I dzil build:  aborting; duplicate files would be produced
10:10:01 < Altreus> It's talking about the README I made
10:10:19 < Altreus> it's making its own I think
10:10:25 < kent\n> You have a config file that is trying to clobber it
10:10:26 < kent\n> correct.
10:10:41 < kent\n> you likely have ReadmeFromPod or something
10:10:41 < Altreus> ah
10:10:47 < Altreus> it's just got the abstract in it
10:10:49 < Altreus> let me see
10:10:55 < kent\n> tl;dr , you are using an @bundle such as @classic
10:11:03 < Altreus> ah @Basic
10:11:07 < kent\n> and you *really* should look inside those bundles to see what they are doing
10:11:23 < Altreus> I was told to do that in several places but didn't see anywhere that told me to do it
10:11:25 < kent\n> I personally suggest you not use bundles until you know what they include
10:11:39 < Altreus> er
10:11:44 < Altreus> I didn't see anywhere that told me what it meant
10:12:00  * kent\n sees lots of people get fuckups when they put [UploadToCpan] in their dist.ini and its already there via bundle
10:12:11 < kent\n> @ = bundle
10:12:14 < Altreus> It is mildly - very - irritating when tutorials tell you to do stuff but don't tell you what it's for
10:12:15 < kent\n> [Foo] # package
10:12:19 < kent\n> [@Foo] # bundle
10:12:29 < Altreus> I will undo this bundle
10:12:42 < kent\n> [=Real::Path::To::Package] # not a Dist::Zilla::Whatever
10:12:51 < kent\n> bundles are in Dist::Zilla::PluginBundle::*
10:13:42 < Altreus> I have found - maybe - the page I was looking for
10:14:25 < kent\n> http://search.cpan.org/search?query=Dist%3A%3AZilla%3A%3APluginBundle%3A%3A&amp;mode=module&nbsp; # people tend to use these to implement "Do it my way" and share that way across many modules
10:15:49 < kent\n> http://search.cpan.org/~rjbs/Dist-Zilla-4.102345/lib/Dist/Zilla/PluginBundle/Basic.pm # what you are using
10:16:37 < kent\n> Its a good recommendation list, but if you're wanting to configure something manually, its sometimes ( often? ) less than helpful =)
10:17:48 < kent\n> 10:11:23 < Altreus> I was told to do that in several places but didn't see anywhere that told me to do it
10:17:48 < Altreus> The defaults seem OK, except the README
10:17:57 < Altreus> yeah that was a fail
10:18:06 < Altreus> I meant I didn't see anywhere that told me what it meant
10:18:14 < kent\n> Elaborate, I don't understand the grammar
10:18:19 < Altreus> the [@Build]
10:18:29 < kent\n> oh. right.
10:18:36 < Altreus> I found a tutorial - reproduced in two places I think - that said to put that
10:18:42 < kent\n> which tutorial? link?
10:18:46 < Altreus> erm!
10:19:07 < Altreus> dunno, it was ages ago and at work
10:19:11  * kent\n does contribute to DZ, and such as requires eliminating teh bullshit docs that are out there
10:19:27 < kent\n> if you can find it again that would be great =)
10:20:12 < kent\n> there's only 3 turorials I know of 1) the ones in the DZil docs, 2) Dzil.org 3) the one by David Golden
10:20:46 < Altreus> kent\n: http://dzil.org/tutorial/new-dist.html&nbsp; now that I understand what @Basic means I can see where it tells me about it but I didn't make the connection when I read it first time
10:21:19 < kent\n> Thanks, I'll try relay this intel back to HQ and we can clarify things =)
10:22:27 < Altreus> Also I am slightly struggling to work out how to sort of unpack the bundle and perform the steps I want, without getting really deep into it
10:22:34 < Altreus> I do like to do one thing at a time after all
10:22:44 < Altreus> Currently I want to make a cpan dist :)
10:39:29 < kent\n> http://cpansearch.perl.org/src/RJBS/Dist-Zilla-4.102345/lib/Dist/Zilla/PluginBundle/Basic.pm
10:39:33 < kent\n> look at the source ;)
10:39:48 < kent\n> for each line in add_plugins
10:39:59 < kent\n> just copy that line into dist.ini with [  ] around it
10:40:12 < kent\n> and then read the docs for each of those plugins and see whether or not you want them =)
10:48:28 < Altreus> ah right
10:48:34 < Altreus> It is becoming clear
10:50:08 < Altreus> Hmm it makes more sense still
10:50:11 < Altreus> cool
10:50:26 < Altreus> This is a useful thing to have seen simply because it makes a penny drop

I added some more text urging users to read the @Basic docs, with a reason why. -- rjbs