Structured Changelogs for ELPA packages

Philip Kaludercic <[email protected]> Sat, 01 Aug 2026 17:39:30 +0000
Newsgroups gmane.emacs.devel
Message-ID <[email protected]>
This message is primarily targeted at package maintainers with the
intention to hear their opinion on the subject:

There is a sub-discussion in bug#81116 about how to extract news from
changelog files in ELPA packages.  Having a system to do so would be
useful as we could include exactly the relevant section from a changelog
in a release email or the atom feed for a package.

The current situation is that we can specify a news source in the
package specification, but the ELPA build server currently doesn't make
any assumptions about the contents of this file.  We use the beginning
of the file to generate a news section on elpa.gnu.org/elpa.nongnu.org
and include part of it in automated release mails, but we don't
currently include them in atom feeds (which is the actual discussion of
bug#81116).  Note that both the website and the emails can and do
include more than just the latest news and most usually cut of the text
mid section.

It seems that there are two main positions we could take to prescribing
some kind of structure that we could exploit to extract the information
from these files:

- The strict approach would be to say that if we want packages to have
  fine-granular news, that they have to use a specific file format, say
  Org-mode and that the sections describing specific releases have to be
  annotated with tags or properties.  The simplest idea would be just to
  require the org-mode file to include a section with a :release: tag,
  e.g.

  * Version 1.2.3 :release:
  Version 1.2.3 of the package foo includes the following new features:
  ...

- The permissive approach would be to allow any kind of file format and
  then search for sections that would likely to contain the news for a
  specific version.  So if you had a NEWS.md and released version 1.2.3,
  then the first line that would look like

  # Version 1.2.3
  Version 1.2.3 of the package foo includes the following new features:
  ...

  then we would extract the subsection for the news of this specific
  version.  For plaintext, it would be more difficult, but failing to
  find a specific release section isn't fatal as we can just fall back
  to our previous strategy.

Are there any other ideas or comments on this question?  My personal
position is that the first approach is preferable, even if that would
require some authors to switch to org-mode, but that is only necessary
if they value improved handling of their changelogs.  The second
approach has the advantage that it would support more packages right
away, but that would come at the cost of possible false positives.