Re: Structured Changelogs for ELPA packages

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

Daniel