Beefy Boxes and Bandwidth Generously Provided by pair Networks
XP is just a number
 
PerlMonks  

What are your best practice recommendations for maintaining CPAN module with GitHub repo?

by nysus (Parson)
on Dec 18, 2017 at 20:03 UTC ( #1205813=perlquestion: print w/replies, xml ) Need Help??

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

TIMTOWTDI. At times, there also seems to be TMWTDI (Too Many Ways To Do It). That's where I feel like I'm at with the Dist::Zilla right now. There are tons of Dist::Zilla bundles out there that allow you to do all kinds of crazy things. Over the past day, I've fell into kind of a rabbit hole exploring all the different options for automating module maintenance on CPAN and on GitHub.

Though I've learned quite a bit, I'm left with many questions at this point and feeling a little lost at sea. I see many developers simply mirroring their CPAN module on GitHub. That's probably convenient, but it seems to entail sorting through a lot of cruft and it's not very inviting to go on GitHub and see all the CPAN related modules. But cpanm allows you to install a cpan module from a GitHub repo so maybe it's worth it for that? And, overall, how much work and effort should go into customizing a release for GitHub as compared to CPAN? For example, is it good to have a different README and install instructions for GitHub compared to CPAN? And is Pod::Weaver the best way to autogenerate the pod or is it easier just to rely on a default template that you modify? Also, some more basic questions: when do you commit to GitHub vs. releasing to GitHub and CPAN?

I have a bunch of other questions but I was wondering if I could get some basic advice and hear how others are using Dist::Zilla/CPAN/GitHub to try to find an optimal software release solution. Thanks.

$PM = "Perl Monk's";
$MCF = "Most Clueless Friar Abbot Bishop Pontiff Deacon Curate Priest";
$nysus = $PM . ' ' . $MCF;
Click here if you love Perl Monks

  • Comment on What are your best practice recommendations for maintaining CPAN module with GitHub repo?
  • Download Code

Replies are listed 'Best First'.
Re: What are your best practice recommendations for maintaining CPAN module with GitHub repo?
by stevieb (Canon) on Dec 18, 2017 at 21:02 UTC

    I wouldn't call it "mirroring" per-se. Github is where the modifications are stored, CPAN where the final product for each release goes.

    I have a few pre-configured files that get brought into each project I create, primarily a .gitignore and a MANIFEST.SKIP. Each manages to ignore the files that aren't relevant to its own process. Very rarely to I have to edit these files to make it specific to a project.

    I do my work in my repo, then when all tests pass (most projects uses Travis-CI and/or Appveyor along with Coveralls.io. Some can't because they rely on external functionality or specific hardware, so I have my own in-house unit test automation software as well. Once all tests pass across the board, I do one last update to changes (essentially putting today's date in the current change log entry), tag it as a release, do a make dist, and upload it to the CPAN.

    Immediately after that process, I put a new entry in my change log:

    Changes history for My::Perl::Application 0.31 UNREL - 0.30 2017-12-18 - did this - did that

    ...bump my version numbers in the required files, do a commit bumped ver to 0.31 and start the process over again. When I look at my code on the CPAN for a specific release, it will be exactly the same when I look at the release tag for the software in Git/Github.

    Of course that's a quick overview, but that's how I go about it. It's such a memory process from dist start through publishing that it isn't even worth me automating anything beyond that.

    It may help if you explained what you'd *like* to see the process look like first, lay that out for us, then get guidance on specific pieces, instead of starting without any idea/plan which is very difficult indeed.

      Oh, and no, I don't use dzil. I find it exceptionally annoying, one of the big ones is there's no Makefile.PL, so you can't just download and test around (easily). I did hack my automation software to be able to test dzil distributions through some trickery, but you have to have the binary installed in the first place anyhow.

      Module::Starter's module-starter binary to get things set up, then modify your process from there. It's trivial to have a script to pull in a couple of files you commonly use, but since it's a 2 second process, I do that manually.

      I was actually doing some thinking on what I'd like to see in the process and it mostly comes down to 1) automating POD creation but still making a POD that has touches of a human element and 2) coming up with a great README file based on context (one for GitHub and one for CPAN).

      In fact, I started writing up a rough idea of what would go into an ideal README file. It would be something like this:

      OVERVIEW This software code, written in the Perl programming language, <%SUMMAR +Y OF MODULE IN 1/2 SENTENCE IN AS NON-TECHNICAL LANGUAGE AS POSSIBLE +%> WHO IS IT FOR? The target audience for this software is <% DESCRIBE WHO A TYPICAL USE +R MIGHT BE %> who is trying to <% DESCRIBE THE PROBLEM TRYING TO BE S +OLVED %> IS THIS SOFTWARE CURRENTLY MAINTAINED? This software is in an <% EARLY|ACTIVE|INACTIVE %> state of developmen +t <% AND|BUT %> is considered to be <% EXPERIMENTAL|UNSTABLE|MATURE % +>. Bug reports are <% LARGELY IGNORED|ACTIVELY RESPONDED TO %>. To learn +how to report bugs, see the BUG REPORTING section on the man page at +<% LINK TO BUG REPORTING SECTION ON MAN PAGE %> IS THIS SOFTWARE EASY TO USE? <% OVERVIEW OF SKILLS & EXPERIENCE NEEDED OR EXPECTED %> HOW DOES IT WORK? Please see the man page at <% LINK TO MAN PAGE %> for how to use this +software. IS THIS PROJECT ACTIVELY LOOKING FOR HELP? This project <% IS|IS NOT %> seeking assistance from other developers +at this time. Pull requests and other contributions <% WILL|WILL NOT +%> likely get ignored. <% BULLET LIST AREAS WHERE PROJECT COULD NEED HELP HERE %> Please consult the man page at <% LINK TO MAN PAGE AND OTHER RESOURCES + %> if you would like to get involved. HOW DO I GET IT INSTALLED? Please, follow the instructions at <% LOCATION OF INSTALLATION GUIDE % +> OTHER INFO Copyright, authorship, and basic license can go here.

      I want to be able to easily generate a README file similar to that quickly and easily. Probably just a simple templating solution is all I need. Dist::Zilla can do that but it's been a little rough figuring out the best way to actually execute it.

      $PM = "Perl Monk's";
      $MCF = "Most Clueless Friar Abbot Bishop Pontiff Deacon Curate Priest";
      $nysus = $PM . ' ' . $MCF;
      Click here if you love Perl Monks

        My README is usually just one of these:

        pod2readme lib/Main/Module.pm

        ...but some do like to have a custom README that has different information. Because my distributions vary wildly as to what they do and intended target, I always write out my documentation manually, and keep a list of any methods or uses that I've changed, so I can update the docs before release. Things vary too wildly between the dists I write to really have any form of documentation automation that I wouldn't have to continuously maintain and update, so there's more work there as opposed to just hammering it out manually.

        Writing my docs manually ensures that I have full understanding of my code. I use Test::Pod and Test::Pod::Coverage to ensure all POD is in place, and beyond that, any failed unit tests will tell me that I've changed the code enough to do a review of the tests, the code (in case the change isn't what I expected) and of course the POD.

        I am not in favour really of automating documentation; to me, it's an extension of the code, so it doesn't bother me to write it.

        To further, I do periodic reviews of random distributions I have, validating the documentation is accurate through actually using the code per what the docs say.

        It sounds like you need a simple Template::Toolkit set up if what you're trying to do is auto-populate some simple documents.

Re: What are your best practice recommendations for maintaining CPAN module with GitHub repo?
by Mr. Muskrat (Canon) on Dec 18, 2017 at 20:54 UTC

    Multiple people tried to discourage you from using Dzil in your previous thread. Here's my anti-answer...

    You decided to start using learning how to swim in North Atlantic instead of the shallow end of a swimming pool. You've mastered the doggie paddle but you're far from shore in cold, rough water, the wind is starting to pick up and... Wait, was that a shark that just swam past? You feel like you just might drown or get eaten at any point.

    Take a deep breath, open your eyes and stand up. Fortunately you are in the shallow end of the swimming pool because you can switch to a simpler tool at any point (with some work) if you choose to do so.

      I am just seeing the other replies now. Haven't been able to get to them yet. I don't ignore any response on here, except for Anonymous Monks'.

      As noted, I am interested in Dist::Zilla because 1) that is what is being used by Dancer2 and 2) I was looking for ways to automate things and it does this nicely.

      Regarding deep/shallow end, yeah, you are right. But it is definitely nice to be able instantly trigger a bunch of automation with a few keystrokes. Sure, it offers much more power than what I need at this point writing my hokey little module. However, getting familiar with it has unlocked a lot of the mystery of the process for me and has gotten me a bit fascinated by it. It's approach with the .ini files set up like they are as a kind of mini programming language was something I've never seen before and I thought that was interesting.

      $PM = "Perl Monk's";
      $MCF = "Most Clueless Friar Abbot Bishop Pontiff Deacon Curate Priest";
      $nysus = $PM . ' ' . $MCF;
      Click here if you love Perl Monks

Re: What are your best practice recommendations for maintaining CPAN module with GitHub repo?
by marto (Cardinal) on Dec 18, 2017 at 21:06 UTC

    Github is version control, not a mirror of cpan releases. Review your last few threads and the responses. You've ignored a lot of advice of great benefit.

      I am just seeing the other replies now. Haven't been able to get to them yet. I don't ignore any response on here, except for Anonymous Monks' (most of the time).

      $PM = "Perl Monk's";
      $MCF = "Most Clueless Friar Abbot Bishop Pontiff Deacon Curate Priest";
      $nysus = $PM . ' ' . $MCF;
      Click here if you love Perl Monks

        I don't ignore any response on here, except for Anonymous Monks' (most of the time).
        You ignore what people say, not that they say anything, followed by childish responses. 1205580 et cetera. With your problem, you can not afford to ignore anyone.
Re: What are your best practice recommendations for maintaining CPAN module with GitHub repo?
by hippo (Bishop) on Dec 18, 2017 at 21:55 UTC
    it's not very inviting to go on GitHub and see all the CPAN related modules

    What an odd thing to think. I take the opposing view.

    how much work and effort should go into customizing a release for GitHub as compared to CPAN?

    Github is not a release channel, it is a publicly-accessible, managed VCS repository.

    is Pod::Weaver the best way to autogenerate the pod or is it easier just to rely on a default template that you modify?

    Autogenerating POD is lazy and not in a good way, so don't do that.

    Also, some more basic questions: when do you commit to GitHub vs. releasing to GitHub and CPAN?

    See above, you don't "release to github".

    I was wondering if I could get some basic advice and hear how others are using Dist::Zilla/CPAN/GitHub to try to find an optimal software release solution.

    Optimal in terms of what, exactly? Fewest bugs or most extensive documentation or easiest for others to contribute or efficient for you as release roller or most structured commit logs or ... ?

    Perhaps it's time to heed what almost everyone has been suggesting and stay away from Dist::Zilla until you've answered all the questions you posed to your own satisfaction. It doesn't seem to be helping you. Good luck.

Re: What are your best practice recommendations for maintaining CPAN module with GitHub repo?
by ikegami (Patriarch) on Dec 19, 2017 at 19:20 UTC

    how much work and effort should go into customizing a release for GitHub as compared to CPAN?

    You're confusing deploying and releasing. You deploy changes (patches) to your module via GitHub, and you release versions (tarballs) to your users via CPAN.


    Because GitHub is far more than just a git repository host, GitHub can technically be used to host releases as well, but noone does that —at least not exclusively— because cpan won't find them.

    On the other hand, some people use GitHub as their bug tracker instead of rt.cpan.org. You can specify your preferred bug tracker in your release's (distribution's) META file.

Re: What are your best practice recommendations for maintaining CPAN module with GitHub repo?
by nysus (Parson) on Dec 18, 2017 at 20:57 UTC

    This is somewhat related: What should be in a README?

    I want to strive to automate the docs but also I also want to put care into making them useful. You can lose some of that when everything is automated. Yes, I want to make the automation process painless, but I also want to make it easy to include stuff that should handcrafted as well.

    $PM = "Perl Monk's";
    $MCF = "Most Clueless Friar Abbot Bishop Pontiff Deacon Curate Priest";
    $nysus = $PM . ' ' . $MCF;
    Click here if you love Perl Monks

A reply falls below the community's threshold of quality. You may see it by logging in.

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others meditating upon the Monastery: (5)
As of 2022-06-29 09:43 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    My most frequent journeys are powered by:









    Results (96 votes). Check out past polls.

    Notices?