Re: Add versions.json endpoint with latest release information

On Fri, Apr 30, 2021 at 5:59 AM Magnus Hagander <magnus(at)hagander(dot)net> wrote:

> * Why do we care about sorting the keys? Not that it matters much, but
> it mostly seems a bit silly, but if there is a reasoning behind it
> there's no problem -- I'd just like to know what the reasoning is.
>

It's sorted to ensure a completely stable HTTP response. It shouldn't
matter or be relied upon by any external consumer of the data, but it's
mildly convenient to know that the handler response will be byte-for-byte
consistent regardless of Python version or if the response is cached. It
makes testing a tad easier too as you can rely on an "==" on the raw
response text.

* It reports major version as "13.0", not "13". It's correct for
> versions prior to 10.
>

Is there an updated set of sample data? I cloned the project and followed
the dev setup instructions, but the initial data it loads only goes up to
8.4.

> * In the XML/RSS feed we include a link to the release notes for the
> version. Do we want to do that here as well? I'm thinking probably not
> because (1) the RSS needs a clickable link, that's probably the only
> reason it's there, and (2) release notes can now be found at
> /docs/release/<version>/, which was not the case at the time of the
> RSS feed being created. But I wanted to raise it for discussion in
> case people would find it useful?
>

No, I don't think it needs the link either.

> * I'm thinking the orignal name "latestminor" is actually better than
> "minor" -- the previous minor releases still exist after all.
>

I was back and forth on this as well. I figured the endpoint itself
represents the latest for each major version so having it be "minor" made
more sense.

A separate endpoint with all historical minor versions could then also have
the same structure.

* Would it make sense to have an actual query parameter like
> "?current=1" or something that would give you *just* the current
> version? To avoid having to download all? And maybe also
> "?supported=1" to get just supported versions? To avoid having to do
> those filterings client side?
>

My own use case would use the full list though I can see both "current" and
"supported" being useful as well.

If we structure the URL to support that in the future I think that's fine.
Rather than query parameters could have totally separate end points:

/versions/all.json - Array response with latest of each major version
/versions/supported.json - Array response with list of supported versions
/versions/current.json - Object response of only current version

I don't know which of those would play nicer with how the HTTP caching
works. The expectation is that these endpoints are going to be hit
repeatedly by things like CI platforms so we should get that part right.

Regards,
-- Sehrope Sarkuni
Founder & CEO | JackDB, Inc. | https://www.jackdb.com/