Mailing List Archive

Pre-RFC: perldelta naming
Dear Porter,
currently the perldelta pod is renamed on every version to
perl$version_without_dotsdelta on every release.
I'd like to ask if we can't name the file that way when it is created so
that it doesn't have to get renamed later?
Keeping perldelta as an index for all available version specific files,
maybe highlighting the major changes, new features, important bug- and
security fixes, if something relies on its existence.

Thanks, Alex
Re: Pre-RFC: perldelta naming [ In reply to ]
On 2022-01-07 12:26 a.m., Alexander Hartmaier wrote:
> Dear Porter,
> currently the perldelta pod is renamed on every version to
> perl$version_without_dotsdelta on every release.
> I'd like to ask if we can't name the file that way when it is created so that it
> doesn't have to get renamed later?
> Keeping perldelta as an index for all available version specific files, maybe
> highlighting the major changes, new features, important bug- and security fixes,
> if something relies on its existence.
>
> Thanks, Alex

I like this idea. Create every Perl Delta file from now on using its final name
inclusive of version number, and have the generic "perldelta" be a concise index
of sorts that mainly points to the numbered file for the latest version. This
index can also have a brief explanation of how to read the other files and which
ones are most relevant. -- Darren Duncan
Re: Pre-RFC: perldelta naming [ In reply to ]
This suggestion doesn't need to be an RFC (so it doesn't need to be a
pre-RFC). It's a valid suggestion, but we're rather over-using the "I'm
going to call it a pre-RFC" thing now. And pre-RFC's were supposed *only*
to be the pitch for "do I write a proper RFC". All this seems to have got
a bit confused.

On Fri, Jan 07, 2022 at 12:50:07AM -0800, Darren Duncan wrote:
> On 2022-01-07 12:26 a.m., Alexander Hartmaier wrote:
> > Dear Porter,
> > currently the perldelta pod is renamed on every version to
> > perl$version_without_dotsdelta on every release.
> > I'd like to ask if we can't name the file that way when it is created so
> > that it doesn't have to get renamed later?
> > Keeping perldelta as an index for all available version specific files,
> > maybe highlighting the major changes, new features, important bug- and
> > security fixes, if something relies on its existence.
> >
> > Thanks, Alex
>
> I like this idea. Create every Perl Delta file from now on using its final
> name inclusive of version number, and have the generic "perldelta" be a
> concise index of sorts that mainly points to the numbered file for the
> latest version. This index can also have a brief explanation of how to read
> the other files and which ones are most relevant. -- Darren Duncan

I know that we changed it, but I couldn't remember why. I *can* remember
that there were pain points both ways. I went for a quick look through git
history (available to all of us). The change was this:

Author: Florian Ragwitz <rafl@debian.org>
Date: Sun Aug 22 10:43:37 2010 +0200

Move the latest perldelta to pod/perldelta.pod

This way patches including perldelta entries will apply properly, no matter when
they are applied. If there's conflicts, they'll at least be in the right file.


Since that change there have been a whole bunch of improvements in our
"tooling" for making releases, some of which assume an unchanging filename
as their target. So if we think that the trade off is worth it, changing
back to the old plan is *not* as simple as reverting that commit.

I'd be interested as to what release managers and folks who regularly apply
patches think. (Or if anyone wants to try implementing this change and then
roll a release tarball locally to see how it works)

Nicholas Clark
Re: Pre-RFC: perldelta naming [ In reply to ]
On Fri, Jan 7, 2022, at 3:59 AM, Nicholas Clark wrote:
> I'd be interested as to what release managers and folks who regularly apply
> patches think. (Or if anyone wants to try implementing this change and then
> roll a release tarball locally to see how it works)

I'm not fussed. Very occasionally I get confused by this setup, but I'm sure I'd get a little confused by the alternative. But I think that the second kind of confusion would only affect people who had been poisoned by the current setup. ;-)

In other words: as a once-frequent releaser, I'm not sure I'd be bothered by the change, and the question is probably "Wait, why did we do this, again?"

--
rjbs
Re: Pre-RFC: perldelta naming [ In reply to ]
On Sat, Jan 8, 2022 at 8:51 AM Ricardo Signes <perl.p5p@rjbs.manxome.org> wrote:
>
> On Fri, Jan 7, 2022, at 3:59 AM, Nicholas Clark wrote:
>
> I'd be interested as to what release managers and folks who regularly apply
> patches think. (Or if anyone wants to try implementing this change and then
> roll a release tarball locally to see how it works)
>
>
> I'm not fussed. Very occasionally I get confused by this setup, but I'm sure I'd get a little confused by the alternative. But I think that the second kind of confusion would only affect people who had been poisoned by the current setup. ;-)
>
> In other words: as a once-frequent releaser, I'm not sure I'd be bothered by the change, and the question is probably "Wait, why did we do this, again?"

I would not worry about release managers because I suspect in every
case ever they have always known the number of the release they are
rolling :-). I would worry about Jane Programmer who submits the
occasional PR and has to trawl through the pod/ directory to figure
out which delta to update, which will most likely be the wrong one by
the time the PR is merged. Unless someone is paying very close
attention and takes manual steps to modify the PR before merging, as
often as not a previous perldelta rather than the current one will get
updated.

I believe avoiding such disconnects and lowering the friction a new or
occasional contributor faces provide the answer to "why did we do
this?" and this along with, as Nicholas points out, the fact that
changing would break things that are currently working and would
require effort to get unbroken, make me wary of changing how this
works. Plus, there were no actual reasons/benefits provided for
making the change other than what we do now involves renaming a file.
Which doesn't seem to be causing any problems I'm aware of.

There was an unrelated suggestion to have an index of all the
perldeltas. We could resurrect perlchanges.pod and have it be an
automatically-generated index of all the perldeltas, or we could
revamp perlhist so that releases are in descending order and have
links to the perldeltas (where available). Patches welcome, as we
used to say.
Re: Pre-RFC: perldelta naming [ In reply to ]
On Mon, Jan 10, 2022, at 8:40 AM, Craig A. Berry wrote:
> I would not worry about release managers because I suspect in every
> case ever they have always known the number of the release they are
> rolling :-). I would worry about Jane Programmer who submits the
> occasional PR and has to trawl through the pod/ directory to figure
> out which delta to update, which will most likely be the wrong one by
> the time the PR is merged. Unless someone is paying very close
> attention and takes manual steps to modify the PR before merging, as
> often as not a previous perldelta rather than the current one will get
> updated.

Thanks, Craig, that's a really excellent point, and makes me think that "perldelta is the next one" has a bunch of value.

--
rjbs
Re: Pre-RFC: perldelta naming [ In reply to ]
On Wed, Jan 12, 2022 at 12:30 PM Ricardo Signes <perl.p5p@rjbs.manxome.org>
wrote:

> On Mon, Jan 10, 2022, at 8:40 AM, Craig A. Berry wrote:
>
> I would not worry about release managers because I suspect in every
> case ever they have always known the number of the release they are
> rolling :-). I would worry about Jane Programmer who submits the
> occasional PR and has to trawl through the pod/ directory to figure
> out which delta to update, which will most likely be the wrong one by
> the time the PR is merged. Unless someone is paying very close
> attention and takes manual steps to modify the PR before merging, as
> often as not a previous perldelta rather than the current one will get
> updated.
>
>
> Thanks, Craig, that's a really excellent point, and makes me think that
> "perldelta is the next one" has a bunch of value.
>

One thing that could be changed without breaking this is to have the
perldelta copied to its new version during the RMG distribution process,
rather than on installation - this would fix its availability on metacpan,
as discussed in https://github.com/metacpan/metacpan-web/issues/2587 and
related issues.

-Dan
Re: Pre-RFC: perldelta naming [ In reply to ]
We discussed perldelta naming at the last PSC meeting, and agreed that there’s too much benefit to having the file called perldelta.pod in blead, specifically so people can be told "if you make a change of note, update perldelta.pod", rather than having to put [version].[revision] in there.

And it’s somewhat handy that I can type `perldoc perldelta` to find the changes in my locally installed version of Perl.

Dan wrote:
> One thing that could be changed without breaking this is to have the perldelta copied to its new version during the RMG distribution process, rather than on installation - this would fix its availability on metacpan, as discussed in https://github.com/metacpan/metacpan-web/issues/2587 and related issues.
The key word here presumably being *copied*? So when 5.35.9 is released, it would have both perldelta.pod and perldelta5359delta.pod, with identical contents, and the RMG would still have the post-release action to create a new perldelta.pod in blead.

This feels like a good step.

Neil
Re: Pre-RFC: perldelta naming [ In reply to ]
On Thu, Feb 3, 2022 at 4:59 PM Neil Bowers <neilb@neilb.org> wrote:

> We discussed perldelta naming at the last PSC meeting, and agreed that
> there’s too much benefit to having the file called perldelta.pod in blead,
> specifically so people can be told "if you make a change of note, update
> perldelta.pod", rather than having to put [version].[revision] in there.
>
> And it’s somewhat handy that I can type `perldoc perldelta` to find the
> changes in my locally installed version of Perl.
>
> Dan wrote:
>
> One thing that could be changed without breaking this is to have the
> perldelta copied to its new version during the RMG distribution process,
> rather than on installation - this would fix its availability on metacpan,
> as discussed in https://github.com/metacpan/metacpan-web/issues/2587 and
> related issues.
>
> The key word here presumably being *copied*? So when 5.35.9 is released,
> it would have both perldelta.pod and perldelta5359delta.pod, with identical
> contents, and the RMG would still have the post-release action to create a
> new perldelta.pod in blead.
>

Agreed, even after installation there's definitely institutional knowledge
about the existence of the perldelta file, I don't think it is worth
changing its presence at any point.

-Dan
Re: Pre-RFC: perldelta naming [ In reply to ]
On Thu, Feb 3, 2022 at 11:00 PM Neil Bowers <neilb@neilb.org> wrote:

> We discussed perldelta naming at the last PSC meeting, and agreed that
> there’s too much benefit to having the file called perldelta.pod in blead,
> specifically so people can be told "if you make a change of note, update
> perldelta.pod", rather than having to put [version].[revision] in there.
>
> And it’s somewhat handy that I can type `perldoc perldelta` to find the
> changes in my locally installed version of Perl.
>
> Dan wrote:
>
> One thing that could be changed without breaking this is to have the
> perldelta copied to its new version during the RMG distribution process,
> rather than on installation - this would fix its availability on metacpan,
> as discussed in https://github.com/metacpan/metacpan-web/issues/2587 and
> related issues.
>
> The key word here presumably being *copied*? So when 5.35.9 is released,
> it would have both perldelta.pod and perldelta5359delta.pod, with identical
> contents, and the RMG would still have the post-release action to create a
> new perldelta.pod in blead.
>
> This feels like a good step.
>
> Neil
>
>
Thanks for discussing it!

I understand the advantages for the Perl developers but they are at the
expense of the users.
Can a build step be used to have both?
As a user I don't care about development version changes, just those that
went into a stable release (is that the correct wording for the even
numbered releases?).

For example you currently can't link to the perldelta of the newest stable
release on metacpan because it isn't called perldelta$versionnumber at that
time.
I'm sure there are reasons for not only having a single perldelta where all
versions are documented?!
Re: Pre-RFC: perldelta naming [ In reply to ]
On Fri, Feb 4, 2022 at 2:37 PM Alexander Hartmaier
<alex.hartmaier@gmail.com> wrote:
>
> On Thu, Feb 3, 2022 at 11:00 PM Neil Bowers <neilb@neilb.org> wrote:
>>
>> We discussed perldelta naming at the last PSC meeting, and agreed that there’s too much benefit to having the file called perldelta.pod in blead, specifically so people can be told "if you make a change of note, update perldelta.pod", rather than having to put [version].[revision] in there.
>>
>> And it’s somewhat handy that I can type `perldoc perldelta` to find the changes in my locally installed version of Perl.
>>
>> Dan wrote:
>>
>> One thing that could be changed without breaking this is to have the perldelta copied to its new version during the RMG distribution process, rather than on installation - this would fix its availability on metacpan, as discussed in https://github.com/metacpan/metacpan-web/issues/2587 and related issues.
>>
>> The key word here presumably being *copied*? So when 5.35.9 is released, it would have both perldelta.pod and perldelta5359delta.pod, with identical contents, and the RMG would still have the post-release action to create a new perldelta.pod in blead.
>>
>> This feels like a good step.
>>
>> Neil
>>
>
> Thanks for discussing it!
>
> I understand the advantages for the Perl developers but they are at the expense of the users.
> Can a build step be used to have both?
> As a user I don't care about development version changes, just those that went into a stable release (is that the correct wording for the even numbered releases?).

I have yet to hear of any demonstrated harm to users, and in Neil's
message he mentions that copying the current perldelta to a
version-specific copy at release time "feels like a good step."
Doesn't that give everybody what they want? It will require someone
making changes to the release process.

> For example you currently can't link to the perldelta of the newest stable release on metacpan because it isn't called perldelta$versionnumber at that time.

I must be missing something here. If you want to link to a specific
version, why not just link to a specific version like you would with
any other file in the distribution:

https://metacpan.org/release/XSAWYERX/perl-5.32.0/view/pod/perldelta.pod

https://metacpan.org/release/XSAWYERX/perl-5.34.0/view/pod/perldelta.pod

?

If someone does change the release process to copy the current file to
a version-specific clone, then you will also be able to link to that.

> I'm sure there are reasons for not only having a single perldelta where all versions are documented?!

I think the only reason for not having it is that no one has felt it
was necessary. We're basically using the file system as an index
since the relevant POD files have the version number embedded in them
for prior releases so it's pretty obvious where to find changes for a
particular version. Building an index that links to all of them could
certainly be done if someone wanted to do it, or, as I suggested
earlier, links could be added to perlhist entries.