Future plans?

[nicoddemus]

Howdy!

Was just thinking about creating a tool to upload changelogs to Tidelift and came across yours. 😁

I was wondering what are your future plans regarding this project? Do you intend to make it generally usable by other projects, or is something you plan to use for your own projects only?

Cheers

[jaraco]

Hi Bruno. My preference would be for the project to be as general purpose as possible. I’ve only just started on it so have few opinions about what it should do. See the jaraco/tidelift project (that I merge into other projects) for how I use it. I welcome contributions.

[jaraco]

As for future plans, I want to see if I can find a way to extract release notes mechanically instead of linking to RTD. I’m considering using Reno for producing the changelog, is that’s the next thing I’ll be exploring. Such a mode promises to make release notes for a given version more readily discoverable.

[nicoddemus]

As for future plans, I want to see if I can find a way to extract release notes mechanically instead of linking to RTD.
I’m considering using Reno for producing the changelog

I've given this problem some thought as well. As projects might generate changelogs in completely different ways, automated or manually, I thought the tool could parse the final CHANGELOG produced in order to obtain the text to upload to Tidelift. The "parsing" would actually be very simple, just a line-based regex which identifies where a release notes starts, and would include all lines after that until the next release note is found.

For example:

pytest 4.6.2 (2019-06-03)
=========================

Bug Fixes
---------

- `#5370 <https://github.com/pytest-dev/pytest/issues/5370>`_: Revert unrolling of ``all()`` to fix ``NameError`` on nested comprehensions.

....

pytest 4.6.1 (2019-06-02)
=========================

...

The user could pass "--re=pytest (\d.\d.\d.) \d{4}-\d{2}-\d{2}" on the command line to identify where the changelog for a given version starts (the group in the regex identifies the version).

Then the user can execute:

upload-release-notes "--re=pytest (\d.\d.\d.) \d{4}-\d{2}-\d{2}" CHANGELOG.rst 4.6.2

To upload the release notes for 4.6.2.

The advantage of this method is that it should work for probably any release notes format out in the wild, assuming they are at least consistent.

[jaraco]

The advantage of this method is that it should work for probably any release notes format out in the wild.

I've considered this approach too, but I'm concerned about workflow challenges. You're suggesting parsing the reStructuredText, but it may not be the case that the release notes are available in that format or that format may be unsuitable for processing by TideLift.

Dynamic Release Notes

Consider the keyring project changelog, and compare that to the published changelog, where the release date and hyperlinks to issues are only injected during the publishing stage (using rst.linker), which is something of a hack that runs during the docs build initialization just long enough for the linked rst to be used to build the docs (then is deleted). In this model, there's never a good opportunity for a tool to have access to that linked rst source.

This issue would be magnified if I were able to use more dynamically-generated notes through a tool like reno, something I'm actively pursuing.

Release Notes with special processors

Consider the CherryPy release notes, which rely on the extlinks plugin to render things like :issue:NNN to a hyperlink. These constructs would similarly would be unlikely to be in a format suitable for TideLift's needs.

---

More generally, the amount of dynamism afforded by Sphinx for publishing docs is very high and it's only the output formats of Sphinx that are reliably ready for user consumption.

The TideLift API doesn't accept reStructuredText, but instead expects Markdown, presenting other translation challenges.

It's for these reasons that in my projects, I've been working on making release notes that are published as HTML and have a suitable (predictable, stable) anchor for each released version. Then, using the API, one could generate a link to direct the user to the project's officially-published notes.

Consider the zipp published release notes. Unlike the earlier examples, these docs use v-prefixed headings for each version, meaning the release notes for a particular release can be predictably found at https://zipp.readthedocs.io/en/latest/history.html#vN-N-N where N-N-N is the version number with periods replaced by dashes (Sphinx does this).

My focus has been on making sure that the TideLift release notes are simply a referral to the officially-published release notes, rather than trying to duplicate them in TideLift (which has other implications if release notes ever undergo revision).

I don't have any great recommendations yet, but I'm hoping this sheds some light on my thinking and the challenges many of my projects face.

[nicoddemus]

You're suggesting parsing the reStructuredText

Actually I was thinking of a very dumb parsing using a single regex, which can be customized by the user. My previous example would work just as well for Markdown for example (adjusting the regex of course).

But I see the points you bring, indeed this topic is more complicated than it seems at first (thanks for shedding the light on the various changelog formats out there).

Cheers

[jaraco]

Since considering the above concerns, the Tidelift project has changed a lot. They no longer require release notes to be published to them and instead they extract release notes from Github or other sources, so perhaps it's not a problem for this project to solve.