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

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

[download]

...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.

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

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

    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.

[reply]
[d/l]
[select]
Re^2: What are your best practice recommendations for maintaining CPAN module with GitHub repo?
by nysus (Parson) on Dec 18, 2017 at 22:01 UTC

    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.

    [download]

    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

[reply]
[d/l]

      My README is usually just one of these:

      pod2readme lib/Main/Module.pm

      [download]

      ...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.

[reply]
[d/l]

        I have not gotten around to Test::Pod or Test::Pod::Coverage. It's on my list.

        Right now, I'm thinking I want to strive to get the best of automation without over automating it. Personally, I find it agonizing and tedious if it's not closely related to explaining what the code actually does. I find I much prefer writing tutorials. I've played a little with TT. I'm sure someone has invaded this problem space. I'll tool around cpan some. 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

[reply]

In Section Seekers of Perl Wisdom