Re: Better perldelta management

--000000000000ca9a030656de445c
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Thu, Jul 16, 2026 at 3:18=E2=80=AFPM Paul "LeoNerd" Evans <leonerd@leone=
rd.org.uk>
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?


It sounds like something that would result in a terribly messy git history,
even if it might be convenient from a merge-conflict POV.

Leon

--000000000000ca9a030656de445c
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div dir=3D"ltr"><div class=3D"gmail_quote"><div dir=3D"lt=
r" class=3D"gmail_attr">On Thu, Jul 16, 2026 at 3:18=E2=80=AFPM Paul &quot;=
LeoNerd&quot; Evans &lt;<a href=3D"mailto:[email protected]" target=3D=
"_blank">[email protected]</a>&gt; wrote:<br></div><blockquote class=
=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rg=
b(204,204,204);padding-left:1ex">TL;DR: Let&#39;s try managing `pod/perldel=
ta.pod` by writing little addition<br>
=C2=A0 fragment files that get combined at BLEAD-POINT time.<br>
<br>
<br>
Hi all,<br>
<br>
I&#39;m currently in the middle of merging the billion or so (or at least<b=
r>
it feels like) pending PRs now that we have 5.44.0 out the door. One<br>
thing that is striking me is that a lot of them are causing silly<br>
conflicts simply due to concurrent edits in perldelta.pod. If not for<br>
that one conflicting file, I think there&#39;d be under half the current<br=
>
number of conflicts.<br>
<br>
Additionally, it&#39;s lately quite common practice to do weird things<br>
while writing the actual PRs by omitting that chunk to start with, so<br>
it doesn&#39;t cause conflicts. I feel that overall, this is not a good<br>
plan and I think we can do better.<br>
<br>
I recall that BooK has written a tool that can take multiple .pod files<br>
and merge them together by collapsing sections with the same<br>
leading headings. I feel that this would give us a better way to manage<br>
perldelta additions during normal development.<br>
<br>
I&#39;m thinking something like the following workflow:<br>
<br>
=C2=A01. We `mkdir pod/perldelta.pod.d` and keep it empty initially.<br>
<br>
=C2=A02. During development of a new feature, don&#39;t edit perldelta.pod<=
br>
=C2=A0 =C2=A0 directly but instead *add a new file* in that directory, whos=
e name<br>
=C2=A0 =C2=A0 is some silly throw-away name based on your branch name or PR=
<br>
=C2=A0 =C2=A0 number or whatever. Name doesn&#39;t matter, only the content=
 does.<br>
<br>
=C2=A03. Add a step to the RMG for a BLEAD-POINT release which runs BooK&#3=
9;s<br>
=C2=A0 =C2=A0 tool with the generic template and all the files this directo=
ry, so<br>
=C2=A0 =C2=A0 it spits out the merged file. Some manual shuffling of order =
might<br>
=C2=A0 =C2=A0 be useful, to sort multiple additions in the same section int=
o a<br>
=C2=A0 =C2=A0 good order for relevance, but overall this shouldn&#39;t need=
 much work.<br>
<br>
=C2=A0 =C2=A0 (This is basically the same process by which the individual p=
oint<br>
=C2=A0 =C2=A0 release files get combined into the yearly final release anyw=
ay)<br>
<br>
=C2=A0 =C2=A0 After that tool has run, the new perldelta.pod file can be<br=
>
=C2=A0 =C2=A0 committed and all the fragment files deleted.<br>
<br>
An advantage of that workflow is that normal development merges don&#39;t<b=
r>
make conflicting edits to perldelta.pod, so they&#39;ll merge a lot<br>
cleaner. Also that way, you can locally keep your new file in progress<br>
in your own branch, and know that it won&#39;t conflict if you rebase on<br=
>
blead in the meantime.<br>
<br>
Do folks think that sounds like a workable plan?</blockquote><div><br></div=
><div>It sounds like something that would result in a terribly messy git hi=
story, even if it might be convenient from a merge-conflict POV.</div><div>=
<br></div><div>Leon</div></div></div>
</div>

--000000000000ca9a030656de445c--