search

majensen / perlbolt

Neo4j server agent using Bolt protocol
Apache License 2.0
4 stars 2 forks source link

Add pointer to CPAN for the latest release (#45) #49

Open johannessen opened 2 years ago

johannessen commented 2 years ago

Looks like we’ve kind of decided to release on CPAN first, which makes sense for Perl modules I suppose. This PR closes #45 by documenting this in the readme on GitHub.

Unfortunately, the GitHub readme is currently a copy of the CPAN module documentation. So including a pointer to CPAN on GitHub also means including it on CPAN itself, which doesn’t make a lot of sense.

I’m not sure how you’d like to handle this.

majensen commented 2 years ago

It's not an exact copy; the .md files are created from the pod, with Github links replacing the pod (cpan) links. ./Build author_tasks readme does this. There's probably a way to kludge out certain lines from the pod, if it's a major issue.

But the addition to the .md file will get whacked by the build script.

Personally I'd rather have CPAN hold the "release of record", but there should always be a corresponding tag on Github. If you want to manage the github releases, that ok by me.

johannessen commented 2 years ago

It's not an exact copy; the .md files are created from the pod, with Github links replacing the pod (cpan) links. ./Build author_tasks readme does this. […]

Right. How do I get ./Build?

 

Personally I'd rather have CPAN hold the "release of record", but there should always be a corresponding tag on Github. If you want to manage the github releases, that ok by me.

Agreed on CPAN. I think the git tag is best created by the person doing the PAUSE upload (you), so both can happen at the same time.

With the latest GitHub release pointing to CPAN, no further management should be necessary.

In fact, I think the latest release pointing to CPAN is sufficient to address #45 even without merging this PR #49. I therefore propose to simply close both.

majensen commented 2 years ago

./Build is what you get after you run perl Build.PL It's like 'make' with EU::MM. (Which is one of the reasons I like Module::Build, it's all Perl all the time.)

Sent from my iPhone

On Jan 31, 2022, at 1:10 AM, Arne Johannessen @.***> wrote:

 It's not an exact copy; the .md files are created from the pod, with Github links replacing the pod (cpan) links. ./Build author_tasks readme does this. […]

Right. How do I get ./build?

Personally I'd rather have CPAN hold the "release of record", but there should always be a corresponding tag on Github. If you want to manage the github releases, that ok by me.

Agreed on CPAN. I think the git tag is best created by the person doing the PAUSE upload (you), so both can happen at the same time.

With the latest GitHub release pointing to CPAN, no further management should be necessary.

In fact, I think the latest release pointing to CPAN is sufficient to address #45 even without merging this PR #49. I therefore propose to simply close both.

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because your review was requested.

johannessen commented 2 years ago

Build.PL was removed in 52c9bca25cf583aa1add7bd5585f533cc2e1d56a though.

majensen commented 2 years ago

Wow, you are right - I even noted the move to EU::MM in the Changes. (That's because that system is still better for XS stuff-- I fought with Module::Build on it and gave up.) Obviously Build.PL lived on in my working dir and I'm happily using it. I'll work it in to the current system.

I'm also seeing I've reversed myself from this comment regarding GitHub. Well, I guess I think that the two should stay in sync, but maybe we think of the CPAN distro as the "latest stable release" oder was.

majensen commented 2 years ago

Ok - perl Makefile.PL make will now autogenerate the markdown files from modules. e233a386093211907605522e337ad8f2208904df

johannessen commented 2 years ago

Ah, nice!

About the GitHub releases – as long as whatever release is advertised as “latest” by GitHub either points to CPAN (like for v0.4203 and v0.010) or in fact is the latest release, I guess there is no problem for users. I’m fine with us trying to shoot for both.

So, do we merge this or not?

I see now that neither of us actually updated README.md, which is what this PR was supposed to be about. On my end, this was an oversight. I think it used to be written automatically by ./Build author_tasks readme, but pod2md.PL doesn’t do that so far. Options include:

  1. Replace the current README.md with something that primarily addresses potential contributors / perlbolt developers. Include pointers to CPAN (and possibly your module Markdown files) for perlbolt users.
  2. Change pod2md.PL to duplicate Bolt.md as README.md.

My vote would be for option 1.

Should you choose option 2 instead, merging this PR might help users understand that we consider CPAN the “latest stable release”. But I suppose as long as the latest GitHub release includes a pointer to CPAN (see above), that’s probably enough and this change isn’t really necessary…