http://qs321.pair.com?node_id=11146829

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

I have just released a new version of Business::Stripe::WebCheckout and pretty much as soon as I hit the send button, I realised I had forgotten to update the Changes file... The file uploaded is pretty useless and doesn't even reflect the changes in the last version as I used the information to publish the module from Re: What do I use to release a module to CPAN for the first time?

The Changes file has been updated now and the tarball recreated but CPAN won't let me upload the same version.

What is the best course of action?

Replies are listed 'Best First'.
Re: Module Change Log
by Your Mother (Archbishop) on Sep 12, 2022 at 11:53 UTC

    I read change logs. Deleting and releasing the same version will not work. I’d bump the version (and update the changelog to reflect the action :P) and upload it. Then schedule the current release for deletion. Thanks for the code and the care.

      Deleting and releasing the same version will not work

      I suspected that would be the case which is why I did not try it without asking first.

Re: Module Change Log
by Corion (Patriarch) on Sep 12, 2022 at 13:14 UTC

    For the future, you can have a check in your author tests directory that checks that Changes contains a mention of the current version of the module.

    I have such a test file in my template for distributions, but it relies on a Makefile.PL that is a modulino. Likely, the few modifications necessary to make it work in a general case:

    #!perl -w use warnings; use strict; use File::Find; use Test::More tests => 2; =head1 PURPOSE This test ensures that the Changes file mentions the current version and that a release date is mentioned as well =cut #require './Makefile.PL'; ## Loaded from Makefile.PL #our %module = get_module_info(); my $module = 'Business::Stripe::WebCheckout'; (my $file = $module) =~ s!::!/!g; require "$file.pm"; my $version = sprintf '%0.2f', $module->VERSION; my $changes = do { local $/; open my $fh, 'Changes' or die $!; <$fh> } +; ok $changes =~ /^(.*$version.*)$/m, "We find version $version for $mod +ule"; my $changes_line = $1; ok $changes_line =~ /$version\s+20\d\d-[01]\d-[0123]\d\b/, "We find a +release date on the same line" or diag $changes_line;

      That seems very sensible!

      It looks like I either need to create a new module that extends Module::Starter with that sort of check built in, learn to use a more sophisticated tool to generate the distribution framework or continue to learn how to use GitHub so I can make use of your solution.

        Naah - you can just copy a file like I posted above into your xt/ (or t/) directory. If you put it in the t/ directory and name it (say) 99-changes.t, it will get run automatically whenever you run make test or prove -bl t/. If you put it into xt/, it will only get run when you run it explicitly, as author tests are not run by everybody. You need to remember to run those tests locally though - I always do that by always running prove -bl xt/ t/, but having a test that constantly fails is not great during development either.

        I wrote Dist::Mgr for this exact reason. It comes with a distmgr binary that does all the work.

        It extends Module::Starter for distribution creation, and it automates everything else. Adds Github Actions workflow, adds CI and coverage badges, adds repository information. It has a 'release' feature which runs tests, ensures the MANIFEST is up to date, updates the Changes file automatically with the date and version, pushes to Github to run CI tests, then finally, if all is well, it pushes it onto the CPAN.

        A 'cycle' feature bumps version number information, prepares the Changes file for the next version's changes etc.

        I've been using it for a few years now. It's how I manage all of my Perl distributions.

Re: Module Change Log
by Tux (Canon) on Sep 12, 2022 at 15:38 UTC

    Some links:

    And I fully support the previous answers: release a new version with an updated Changes/ChangeLog file. I *do* read it (if I use a modules/distribution).

    FWIW my own release procedure checks if the ChangeLog has an entry less than 4 days ago. If not, it is most likely I forgot to add an entry.


    Enjoy, Have FUN! H.Merijn

      Thanks for the links Tux - very helpful

      How do you implement checking the age of the Change Log without manually copying a test file over which could also be forgotten?

Re: Module Change Log
by hippo (Bishop) on Sep 13, 2022 at 09:34 UTC
    Ignore it as nobody reads change logs anyway

    Addressing this part in isolation, I hope you're joking.

    In case not, it is worth stating that clear, complete change logs are highly important. When a new version is released the first question a user might ask is "Why?". It could be a security fix or another type of bug fix or a performance enhancement or a new feature or a removal of previously deprecated functionality/syntax or just typo fixes in POD or any combination thereof. The change log informs the user of whether (given their own individual circumstances) they must, should, might, shouldn't or mustn't upgrade.

    If you are writing code yourself which has prerequisites, how do you know which version of those prerequisites your code requires? I often find that my code has casually used some feature of a rapidly-developing module which is not present in older versions. Without a change log there is no simple way to tell which version introduced this feature and therefore which version my code requires.

    If you have different versions of a module running on different systems and some versions are reporting errors when others are not, how can you determine the reason if there is no changelog to enumerate the differences?

    Good change logs are on the long list of things in IT which nobody really notices when they are there but it suddenly becomes clear how important they are when absent.


    🦛

      In case not, it is worth stating that clear, complete change logs are highly important.

      I completely and wholeheartedly agree. In my experience, the effort put into a change log is often representative of the effort put into the software.

      Addressing this part in isolation, I hope you're joking

      I was half joking and half serious.

      The more complex or the more functionality a module has, the more the Change Log is needed. I fully realise that it is important. But, in this case, the module is pretty simple and the change is rather minor, albeit to make it work again. So perhaps a better option would have been ignore it until the next release.

      One file I have left as Module::Starter created it is the README.
      I am not sure there is anything useful I can put in there that isn't already in POD.

      Thoughts of README?

        To my mind, README serves 2 purposes. One is a high-level overview of the dist. With this in mind I will usually include in a README: the current version and release date, a brief description of what the dist does, a list of changes since the last release and the licence and copyright details.

        The other purpose is to tell people new to Perl what to do with the tarball they have just unpacked. So that means including the stuff that Module::Starter has put there already about perl Makefile.PL, etc. and then how to find the more extensive documentation (the POD) which will explain how to use it.


        🦛

Re: Module Change Log
by eyepopslikeamosquito (Archbishop) on Sep 13, 2022 at 08:50 UTC

    Bod, thanks for taking the time to post a clear, well thought-out question that's provoked so many excellent replies!

    In case you want to learn more of the history and culture behind Perl's widely admired testing infrastructure, Perl CPAN test metadata describes:

    ... looking forward to a future (working class) Coventry Consensus. :)

    Updated: Added links for Oslo Consensus, Lancaster Consensus, Berlin Consensus (thanks Tux). Hope I got the definitive links. :)

      thanks for taking the time to post a clear, well thought-out question

      The pleasure is all mine :)
      Not only because it provoked so many excellent replies but because I have learnt more about distribution deployment.

      Many thanks for the links...more bedtime reading...

Re: Module Change Log
by kcott (Archbishop) on Sep 13, 2022 at 05:16 UTC

    G'day Bod,

    "Ignore it as nobody reads change logs anyway"

    I read the Changes file; I know many others do too.

    Given the current version is 1.3, I'd suggest updating that to 1.301 (to reflect the fact that it's a minor change; no code or functionality differences).

    Beyond that, I concur with what others have said.

    — Ken

      Given the current version is 1.3, I'd suggest updating that to 1.301

      Thanks Ken,
      Unfortunately, I saw this too late!

      1.2 was the version with the erroneous Changes file and 1.3 is the minor update