Re: Structured Changelogs for ELPA packages

Arash Esbati <[email protected]> writes:

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

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.

> Best, Arash
>
> Footnotes:
> [1]  https://keepachangelog.com/en/1.1.0/