bug#81116: 31.0.60; [FR] ELPA: Include changelog in the Atom feeds

Daniel Mendler <[email protected]> writes:

> Philip Kaludercic <[email protected]> writes:
>
>> Daniel Mendler <[email protected]> writes:
>>
>>> Philip Kaludercic <[email protected]> writes:
>>>
>>>>> But indeed, I wouldn't worry too much, and if the snapshot feeds are not
>>>>> great, so be it. I usually write "* Development" headers in my
>>>>> changelog, so if you scan for headers including the string "devel" it
>>>>> would work.
>>>>
>>>> To be clear, I was not thinking about just scanning headers, but using
>>>> `org-export-select-tags'.  We should probably get some Org people in for
>>>> ideas if we decide to go this way.
>>>
>>> Okay, yes, but I am not in favor of requiring :tags: in changelogs.
>>
>> I would be interested to hear why not.  It would of course not be
>> required in general, just to get the "better" changelog support
>
> In my opinion it is better to be more permissive, and not prescribe a
> fixed format, in order to increase adoption. Ideally this should just
> work. I have little interest in adapting my changelogs for instance, if
> a simple scan would just work as well. The scanner could be tested
> against a few changelog formats which are currently used by ELPA
> packages.

OK, so this is the question it boils down to.  I think that it would be
good to raise this question among a wider group of package maintainers
to get some more feedback, otherwise this is just the perspective of a
package author and an archive maintainer (to exaggerate) that obviously
have different priorities.

>>> We could use the Org parser to iterate over the headings
>>> (org-map-entries) and then search the title for the version or devel
>>> string.
>>
>> I wasn't aware that Org exposed that API, that would make it easier
>> indeed.  We would then still have to go through all the entries, filter
>> out those that match the regular expresion, parse out the version number
>> and then pick the newest one.
>
> My suggestion would be to rather filter the headlines which match the
> version string instead of actually parsing a format. It must not be
> perfect.
>
>>> But I wonder - is Org the only supported format? I am okay with Org of
>>> course and I prefer it, but I had assumed that Markdown or plain text
>>> works as well. This is why I suggested the regexp approach.
>>
>> I think it is better to just fix a single format for these improve
>> changelogs, as that will make it easier for us in the future, and I'd
>> say Org is better to that end than Markdown let alone plain text since
>> it has an authoritative parser and good extensibility, if we do decide
>> that we need something that property drawers could be useful for in the
>> future.

Another example I thought of is to allow annotating release dates

>
> I don't think this is the way. I am in favor of being more permissive,
> and just handle the changelogs which are already there.

For the record, my position is that it is better to be less permissive
in the beginning and slowly become more permissive.  Case in point, we
didn't prescribe any requirements for the changelog files in the
beginning, to make adoption easier with existing projects that have been
using different conventions.  As a result, it is not possible to
reliably extract any machine readable information from these files that
we could use on the website, atom feeds or for Fediverse bots.  For that
reason, I think that this is a good opportunity to create some order by
providing incentives for packages that follow some specific convention,
without breaking anything for packages that don't.

> To be clear, this feature request is really a low priority detail, where
> the packaging infrastructure could be polished, hopefully with little
> effort. But if it means that we have to prescribe a rigid changelog
> format, create unnecessary churn, or if the implementation is too
> complicated on the ELPA side, I think we should not do it.

I don't think that my suggestion is that rigid or controversial.  I just
say that .org changelogs that use a :release: tag to mark the headings
that describe the latest release are last release are used generate the
contents of the atom feed entry for that release.  The details are of
course up to discussion, but I am surprised that you anticipate that
using a tag would be that controversial.  To me, it seems easier than
having to deal with different kinds of headings

* Version 1.2.3
* Release 1.2.3
* Release of Version 1.2.3
* The release of 1.2.3
* 1.2.3 Changelog
* Changes in 1.2.3
* Version 1.2.3 released
* Announcing Foo 1.2.3
* Announcing Foo 1.2.3
* New Version Bar (1.8.2026)
...

I would anticipate that whatever format we support, people will want us
to relax the format to support whatever their preferred style is, for
the sake of being inclusive, where each change might backfire and cause
more and more false positives.  All in all not the end of the world, but
if we can avoid this sticky situation by just saying "use a tag" then it
seems well worth it for me.

>>>>>>> Daniel