Re: Better perldelta management

On Thu, Jul 16, 2026 at 02:17:43PM +0100, Paul "LeoNerd" Evans wrote:
> TL;DR: Let's try managing `pod/perldelta.pod` by writing little addition
>   fragment files that get combined at BLEAD-POINT time.
> 

Having spent some time working on perldelta, this was one of the ideas
we discussed before ending up on the merging script now documented in
Porting/release_managers_guide.pod.

I think we rejected the idea at the time because it was too different
from the established norms, and merging the development deltas into the
blead final one was mimicking what we were already doing manually. We
went with the least disruptive option (and actually simplified my
initial script to be as dumb as possible to avoid the possibility of
data loss).

> I'm currently in the middle of merging the billion or so (or at least
> it feels like) pending PRs now that we have 5.44.0 out the door. One
> thing that is striking me is that a lot of them are causing silly
> conflicts simply due to concurrent edits in perldelta.pod. If not for
> that one conflicting file, I think there'd be under half the current
> number of conflicts.

I will note that this is not the usual workflow for a blead final, after
a feature freeze. It is, however typically what's happening in a regular
bleadpoint release. Except you've hit all the conflicts at once, when in
general every individual who merges a PR has to deal with the conflicts,
one at a time. Your current pain level is kind of an exception.

> Additionally, it's lately quite common practice to do weird things
> while writing the actual PRs by omitting that chunk to start with, so
> it doesn't cause conflicts. I feel that overall, this is not a good
> plan and I think we can do better.

And so we end up adding the deltas *after* the merge, having the
release manager call out for deltas a few days before the release,
instead of keeping the delta nicely tugged in the branch, as work
continues on the feature.

I wonder if this new approach might lead to longer individual deltas.

> I recall that BooK has written a tool that can take multiple .pod files
> and merge them together by collapsing sections with the same
> leading headings. I feel that this would give us a better way to manage
> perldelta additions during normal development.

The script is Porting/merge-deltas.pl, which was written to merge the
sections from the individual deltas of the development branch into the
final perldelta. It does not remove the editing work (especially for
features that changed a lot between development releases), but that
eliminates the tedious and error prone copy/pasting between 10 or more
deltas and the final one.

> I'm thinking something like the following workflow:
> 
>  1. We `mkdir pod/perldelta.pod.d` and keep it empty initially.
> 
>  2. During development of a new feature, don't edit perldelta.pod
>     directly but instead *add a new file* in that directory, whose name
>     is some silly throw-away name based on your branch name or PR
>     number or whatever. Name doesn't matter, only the content does.
> 
>  3. Add a step to the RMG for a BLEAD-POINT release which runs BooK's
>     tool with the generic template and all the files this directory, so
>     it spits out the merged file. Some manual shuffling of order might
>     be useful, to sort multiple additions in the same section into a
>     good order for relevance, but overall this shouldn't need much work.

I think step 3 would be a little different. The sections can be managed
by keeping the =head1/=head2 in the tiny file, and the order of the
different elements in the same section can be inferred from the moment
that file was mergedi (or last edited).

>     (This is basically the same process by which the individual point
>     release files get combined into the yearly final release anyway)

Kind of, yeah.

>     After that tool has run, the new perldelta.pod file can be
>     committed and all the fragment files deleted.
> 
> An advantage of that workflow is that normal development merges don't
> make conflicting edits to perldelta.pod, so they'll merge a lot
> cleaner. Also that way, you can locally keep your new file in progress
> in your own branch, and know that it won't conflict if you rebase on
> blead in the meantime.
> 
> Do folks think that sounds like a workable plan?

The main benefit in my mind is that the delta for a given change can be
kept alongside the changes themselves, in the branch, until it's merged.
And that removes conflict opportunities (at least regarding perldelta).

The script will need to be adapted, since it's going to take the content
from the pod/perldelta.pod.d/ directory, and optionally from the
developement perldeltas when building the blead final release.

This sounds very doable.

-- 
 Philippe Bruhat (BooK)

 Where'er you go, you never know-        /   The reason someone hates you-
 But folks as such- Don't mean as much-  /   As who appreciates you!
                                               (Moral from The Death of Groo)