Re: Structured Changelogs for ELPA packages

--=-=-=
Content-Type: text/plain

Daniel Mendler via "Emacs development discussions."
<[email protected]> writes:

> Philip Kaludercic <[email protected]> writes:
>
>> Hmm, [1] is actually a lot more formal than anything we had discussed in
>> the bug report I mentioned since it prescribes how the contents of the
>> section should be formatted.  Also, it explicitly says "Changelogs are
>> for humans, not machines." which, while I agree in principle, is the
>> opposite direction of what we were trying to solve, since we want to
>> have a machine-friendly and predictable way to detect and extract only
>> the relevant section from a NEWS.org file.

I know this will be controversial, but if we want to maintain that
changelogs are for humans and not machines, the solution is to use an
LLM to produce a standardized changelog from the freeform changelog. I
really don't see a downside to this; this kind of operation is pretty
reliable.

>
> I see these options:
>
> 1. Do not require a fixed changelog format, support them all. Use the
>    first headline matching the version number, or the first lines from
>    the changelog, as I described in bug#81116.
>
> 2. Search for headlines matching a specific pattern. I found these
>    patterns:
>
>    - Keep a Changelog: [1.2.3] - 2026-07-30
>    - Common Changelog: 1.2.3 - 2026-07-30
>    - Towncrier:        1.2.3 (2026-07-30)
>    - Magit style:      v1.2.3 2026-07-30
>
> On the ELPA there seem to exist vastly different formats. For an
> outlier, see for example HY-NEWS from the Hyperbole package. I assume it
> uses the Koutliner format. My packages mostly use a modified Towncrier
> style, but with prefix "Version", e.g., "Version 1.2.3 (2026-07-30)".
> Then there are other packages like Projectile or Company which use the
> exact Towncrier style. Jonas's packages use his style. The files are
> usually either in Org or Markdown format (headlines marked with * or
> #).

Assuming we want purely mechanical parsing, I think it should be
possible to try both of these and see the quality and the % of
unparseable changelogs. This could be a decision driven by data.


>
> Daniel

--=-=-=
Content-Type: text/html

<p>
Daniel Mendler via "Emacs development discussions."
&lt;[email protected]&gt; writes:
</p>

<p>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">

<div>Philip Kaludercic &lt;[email protected]&gt; writes:
</div>
<div>
<br /></div>
<div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">

<div>Hmm, [1] is actually a lot more formal than anything we had discussed in
the bug report I mentioned since it prescribes how the contents of the
section should be formatted.  Also, it explicitly says "Changelogs are
for humans, not machines." which, while I agree in principle, is the
opposite direction of what we were trying to solve, since we want to
have a machine-friendly and predictable way to detect and extract only
the relevant section from a NEWS.org file.

</div></blockquote>

</div></blockquote>
</p>

<p>
I know this will be controversial, but if we want to maintain that
changelogs are for humans and not machines, the solution is to use an
LLM to produce a standardized changelog from the freeform changelog. I
really don't see a downside to this; this kind of operation is pretty
reliable.
</p>

<p>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">

<div>
I see these options:
</div>
<div>
<br /></div>
<div>1. Do not require a fixed changelog format, support them all. Use the
first headline matching the version number, or the first lines from
the changelog, as I described in bug#81116.
</div>
<div>
<br /></div>
<div>2. Search for headlines matching a specific pattern. I found these
patterns:
</div>
<div>
<br /></div>
<div>- Keep a Changelog: [1.2.3] - 2026-07-30
- Common Changelog: 1.2.3 - 2026-07-30
- Towncrier:        1.2.3 (2026-07-30)
- Magit style:      v1.2.3 2026-07-30
</div>
<div>
<br /></div>
<div>On the ELPA there seem to exist vastly different formats. For an
outlier, see for example HY-NEWS from the Hyperbole package. I assume it
uses the Koutliner format. My packages mostly use a modified Towncrier
style, but with prefix "Version", e.g., "Version 1.2.3 (2026-07-30)".
Then there are other packages like Projectile or Company which use the
exact Towncrier style. Jonas's packages use his style. The files are
usually either in Org or Markdown format (headlines marked with * or
#).

</div></blockquote>
</p>

<p>
Assuming we want purely mechanical parsing, I think it should be
possible to try both of these and see the quality and the % of
unparseable changelogs. This could be a decision driven by data.
</p>


<p>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">

<div>
Daniel

</div></blockquote>
</p>

--=-=-=--