Re: 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]
Re^3: What are your best practice recommendations for maintaining CPAN module with GitHub repo? by stevieb (Canon) on Dec 18, 2017 at 22:29 UTC
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]
Re^4: What are your best practice recommendations for maintaining CPAN module with GitHub repo? by nysus (Parson) on Dec 18, 2017 at 22:37 UTC
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]


No such thing as a small change
	PerlMonks