Download Page

[jmcc0nn3ll]

@mojavelinux Can you guys handle the Download page? I was looking at it and don't know how to handle it properly.

Previously I had a txt file that contained the most recent releases by major version number, which I swizzled into a PHP file, letting me dynamically build the download links, etc.

It's better to have one of you do it right once than deal with my back-and-forth attempts.

[mojavelinux]

I do think the download links could be generated as information about releases are readily available. I'd probably use an Antora extension to general content into an AsciiDoc file that's in Antora's content catalog (so in memory). In other words, this is something that should likely be done at build time.

One idea of where to get the release is to consult Maven central. Another is to look at tags in the repository. Is "most recent release by major version number" the criteria for entries in the list? Which major versions (what is the cut off?)

[jmcc0nn3ll]

Pulling from Maven Central makes sense. We only want to generate links for the latest releases of 9.x, 10.x 11.x and 12.x for the main download page. We could provide a second download page for older versions, but that isn't required now.

I'll take a look at how to do this now.

[jmcc0nn3ll]

Would we be better off building an extension and generating the block entirely, or would we build out a set of variables to make a regular table in asciidoc and use variables to create links and such?

Just having this would fit the bill I think.

jetty.12.version jetty.11.version jetty.10.version jetty.9.version

.zip

Or a more asciidoc-looking way for a link.

[mojavelinux]

I did some research on this at the end of last week, so I have some insight to share.

The key is to identify the authoritative source of the download information. I put together a prototype that collects the information necessary to populate the following table from the entries in GitHub Releases.

Can we assume that the GitHub Releases is an authoritative source for the official releases?

If we can, we can start by having an Antora extension call the script that I wrote to collect this information, then inject that data into into the Antora context so it can be used by the download page template. If you like that idea, I can proceed with implementing it.

The benefit of this approach is that it requires 0 maintenance. The information is derived from information already available. If we decide we don't want to run that script on every build, it's possible to connect the script to a GitHub event so it updates a static file in the repository. That way, the Antora extension only has to read a local file each time the site is generated.

[jmcc0nn3ll]

@joakime You good with this?

[joakime]

Some way to verify the downloads would be nice.

We have the sha1 hashes - eg https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-home/12.0.6/jetty-home-12.0.6.tar.gz.sha1 We have gpg signatures - eg https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-home/12.0.6/jetty-home-12.0.6.tar.gz.asc We also have a list of trusted people that make Jetty releases - https://github.com/jetty/jetty.project/blob/jetty-12.0.x/KEYS.txt

[joakime]

Notices about Sun-Setting / EOL are going to be important as well.

For example, Jetty 9 / 10 / 11 are all being sunset.

• https://github.com/jetty/jetty.project/issues/7958
• https://github.com/jetty/jetty.project/issues/10485

Do we want to mention dates? or age?

[mojavelinux]

I don't think it's the responsibility of the site generator to verify downloads. Those should already be verified. That's why we are talking about sourcing this information from an authority that has already done this work. It's rely just supposed to be a simplified view of the release data.

[mojavelinux]

Do we want to mention dates? or age?

The extension could take a configuration as to what majors to flag in this way. In fact, the extension already has a configuration parameter to say when to stop looking for releases (9 being the current threshold). So it could have another as to the lowest that is not EOL.

[mojavelinux]

That's why we are talking about sourcing this information from an authority that has already done this work.

The question is really whether GitHub Releases is an authority for when a version has been released. Or is there some other data source somewhere that is more authoritative? From where I stand, it seems like the GitHub Releases are official given they are referenced in the release issue.

[jmcc0nn3ll]

Process-wise I believe it is an authoritative source, probably the best one. It's part of our release process to make sure that that release record on GitHub is correct. Generating the website is typically a post release process so they should be fine.

One caveat, I believe that record will be updated before artifacts actually drop into Maven Central because of the lag between our releasing the artifacts, and them showing up. We just need to wait until we see artifacts show up and may have been central before we trigger any sort of build and publish of the website.

Having said that, pulling from Maven metadata might even be a little bit more authoritative because then the artifacts are actually there..

[joakime]

I don't think it's the responsibility of the site generator to verify downloads. Those should already be verified. That's why we are talking about sourcing this information from an authority that has already done this work. It's rely just supposed to be a simplified view of the release data.

I agree, it's not the responsibility of the site generator to verify downloads. But that's not what I was asking for.

When there is a download available that itself isn't signed by the author (eg: a msi on windows, a exe installer, a dmg on osx, a pkg on osx, an rpm on ubuntu, etc.) then you place the extra features that allow the user to verify the downloaded artifact near the download links. This includes the checksums, artifact signatures, and the known signature keys.

Eg: https://maven.apache.org/download.cgi

[mojavelinux]

That's outside the scope of what we are doing as part of this migration. If that's something you want and know how to add later, you are definitely free to add that.

[mojavelinux]

Process-wise I believe it is an authoritative source, probably the best one.

Excellent.

One caveat, I believe that record will be updated before artifacts actually drop into Maven Central because of the lag between our releasing the artifacts, and them showing up.

I've added protection against that. In this case, it will fall back to the previous release.