Re: Structured Changelogs for ELPA packages

Philip Kaludercic <[email protected]> writes:

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

I can only tell for AUCTeX, but back then, I had a look at other ELPA
packages and I found a NEWS.org with the format described in 'Keep a
Changelog'[1] to be easy and accessible.  The headers are clearly
defined and formatting with Org is easy so you don't have to be an Org
expert.  Extracting the relevant portions from such a file should be
easy as well.

Best, Arash

Footnotes:
[1]  https://keepachangelog.com/en/1.1.0/