Re: Structured Changelogs for ELPA packages

Andrew Hyatt <[email protected]> writes:

> 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.

We certainly don't want to rely on third-party LLM providers, and I
don't know how efficient+reliable local LLMs are, especially if you want
to factor in the threat of prompt injections.

For me, this is not "changelogs are for humans and not machines", with
the exception of plaintext README files they are written in some kind of
a markup language that a program processes to generate the output that
humans read, the core of the question is if we want to provide the
option for maintainers to have a more structured markup format that they
can use to provide metadata that the ELPA build server can use.  I am
not saying we should enforce it, but trying to figure out if we could
come up with some popular common denominator that package maintainers
would be willing to use.

>>
>> 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