Beefy Boxes and Bandwidth Generously Provided by pair Networks
No such thing as a small change
 
PerlMonks  

Requesting review of new distribution information

by stevieb (Canon)
on Jan 03, 2021 at 15:11 UTC ( [id://11126206]=perlmeditation: print w/replies, xml ) Need Help??

Hey there fellow esteemed Monks!

I've come to the Monastery today to ask a favour. I'm just finishing up a very long desired Perl distribution that I should be ready to publish within a day or two, and would like to ask if some of you would review and provide feedback on the README file to see if A) it's easy to understand, B) explains things unambiguously and thoroughly enough, and C) whether there are any features that I may have overlooked.

The doc should provide enough of an understanding of what I'm trying to achieve, but here's a summary:

I have over 50 CPAN distributions published, and many of them are tools to help the developer. I've always wanted a way to automatically manage my distributions from initial creation, inclusion of other features, and an automatic way to perform a release and the subsequent bump to a new development cycle. This distribution does all of this.

The distribution is named Dist::Mgr, and although I've already released a version to the CPAN, it does not work, and was only put there to verify POD formatting etc. The included binary script is named distmgr, which is what the README focuses on.

The link to the README on my repo is right here.

Replies are listed 'Best First'.
Re: Requesting review of new distribution information
by Discipulus (Canon) on Jan 03, 2021 at 17:54 UTC
    Hello stevieb,

    finally is out! :) I know you were working on this since long time.

    The readme is ok and seems useful software. I already have some feature requests :)

    • support for configuration file. They are user friendly. A single place where I put my personal informations once (name, license(!), cpanid.. ) and my preferences: for example you bump version by 0.01 but I would like to bump by 1
    • support for gitlab: I skipped today from github to gitlab. The first now default to main instead of master as principal branch
    • is well tested under UnfortunateOS? I know I have a weird configuration but I can make test if needed

    Thanks for sharing and nice work!

    L*

    There are no rules, there are no thumbs..
    Reinvent the wheel, then learn The Wheel; may be one day you reinvent one of THE WHEELS.

      Thanks Discipulus!

      I will be adding config file support. The file type will be JSON. I'll also be adding support for other VCS, including Gitlab. The only OSs tested so far are MacOS, Linux and Windows (through Github Actions and Coveralls.io).

      I'm going to do a write up of the software in action when it's done. Essentially a walk through of every step the software takes through its processes so people can understand the defaults, and exactly how much work they no longer have to do.

Re: Requesting review of new distribution information
by 1nickt (Canon) on Jan 03, 2021 at 16:16 UTC

    Hi Steve, the README looks fine to me, nicely concise and clear. (I must say that the considerable effort you have gone to does seem a bit like a rewrite of the Dist::Zilla ecosystem, but I can certainly understand someone wanting to reinvent and streamline that wheel -- although it has never has been anything but a pleasure to work with for me mind you.)


    The way forward always starts with a minimal test.

      Thanks Nick for the feedback!

      I never could get into Dist::Zilla. I have tried though. It always seemed really bloated and required a whole ton of dependencies, where many of my distributions don't have anything but core modules as dependents. Even if the distribution itself wasn't a Dist::Zilla build, needing that distribution to work with my distributions would require installing it on each and every Perlbrew/Berrybrew instance of Perl I use. The Makemaker style of build is something I've always been familiar with, and is easy to implement and use, so I decided that the learning curve wasn't necessary to tackle because I've no other requirement for it.

      The style and layout of my distributions has been consistent for years, and this distribution models exactly what my manual process has been for at least a decade or more.

      Over time, I will add in support for Dist::Zilla and Module::Build build systems in the event others want to use this for their automation, just like I had done with Test::BrewBuild. I'll also be incorporating the possibility to use different VCS and CI platforms (This is my first repo on Github Actions... I got fed up with Travis as I kept running out of their new "credits" and they fired all of their support people, so every time I work on one of my distributions, I'll be moving them too. Hell, perhaps I'll add a function in this distribution to *change* repo/bugtracker instead of just adding them, then I can automate the migration).

Re: Requesting review of new distribution information
by Bod (Parson) on Jan 03, 2021 at 17:21 UTC

    The README seems good to me. It all makes sense despite me not having used GitHub and not understanding some of the terms. But, I feel confident from the README that I would be able to do what I was trying to do.

    From a language point of view, this sentence is a bit weird and I'd split it into two:

    The distmgr command line application that's installed along with the Dist::Mgr Perl distribution provides the facility to manage Perl distributions that you're the author of.

    "The distmgr command line application that's installed along with the Dist::Mgr Perl distribution. It provides the facility to manage Perl distributions that you've authored."

      Thank you for the feedback!

      Regarding Git, get familiar with it. A VCS, ie a Version Control System is by far, hands down, bar none the best tool that any developer has at their disposal. So is the automated Continuous Integration testing and test coverage that can be integrated into them.

      Seriously.

        Regarding Git, get familiar with it.

        Yes I know I need to...
        Only today I jumped in on a bit of a CB discussion about GitLab and went asking the Great God Google for information about comparisons between GitLab and GitHub.

        I intend to share the code for the Raspberry Pi Curtain Controller so that other people might be inspired and perhaps helped when they try something similar. A Git seems the ideal way to do this.

        if you are totally unware of git...

        I wouldn't say totally unaware...
        A little over 20 years ago I did a contract at IBM mainly with Oracle 8. I ended up doing quite a bit of coding. This was the only time I have ever been paid directly to write code...Perl of course...
        We used a CVS so I am familiar with the principle but I cannot remember anything especially useful about it.

        Thanks for the link - I shall work through that tutorial this week before I start properly back to work next week after the festive break.

Re: Requesting review of new distribution information
by Anonymous Monk on Jan 07, 2021 at 22:28 UTC
    Possibly the only thing I might suggest is that you divide the first section into "Description," then "Details." Rename the existing section and add another in front of it. In that section, spell out the value-proposition in non-technical terms: "why should I use this tool to prepare my distribution?" Having thus set the context, instead of presuming that the reader already knew what they were, move on to the "Details."

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perlmeditation [id://11126206]
Approved by haukex
Front-paged by marto
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others browsing the Monastery: (6)
As of 2024-04-24 03:36 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found