Re: Better perldelta management

This sounds reasonable to me. I'll follow whatever the group decides is 
best.

-- Scottchiefbaker

On 7/16/2026 6:17 AM, 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.
>
>
> Hi all,
>
> 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.
>
> 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.
>
> 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.
>
> 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.
>
>      (This is basically the same process by which the individual point
>      release files get combined into the yearly final release anyway)
>
>      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?
>