I can’t figure out how the current downloads page is generated. It’s evident
that there’s a text file with version info that is used in the generation, but
where the base text comes from is not evident to me.
Furthermore, AFAICT the current changelog links are all broken (I think the
generation mechanism assumes svn rather than git).
1. I’ve prototyped a replacement that I at least find more self-documenting.
The version source data would be in a yaml file (or json, but yaml is more
human-friendly). A typical entry would be something like
——
subprojects:
- title: Atomos
artifactId: org.apache.felix.atomos
version: 1.0.0
——
I think this is pretty easy to understand/modify and better than the current
text file.
The slightly less satisfactory part is the formatting for the output, which
currently looks like:
——
[cols="6*",opts="headers"]
|===
|Module
|Version
|Binary
|tar.gz Source
|zip Source
|changelog
|===
jsonpathTable2::example$downloads.yml['$.subprojects.*',
'title|version|`{mirror}/$\{artifactId}-$\{version}.jar{query}[jar]
({dist}/$\{artifactId}-$\{version}.jar.asc[asc],
{dist}/$\{artifactId}-$\{version}.jar.sha1[sha1])` |!!targz ?
`{mirror}/$\{artifactId}-$\{version}-source-release.tar.gz{query}[tar.gz]
({dist}/$\{artifactId}-$\{version}-source-release.tar.gz.asc[asc],
{dist}/$\{artifactId}-$\{version}-source-release.tar.gz.sha1[sha1])` : ""
|`{mirror}/$\{artifactId}-$\{version}-source-release.zip{query}[zip]
({dist}/$\{artifactId}-$\{version}-source-release.zip.asc[asc],
{dist}/$\{artifactId}-$\{version}-source-release.zip.sha1[sha1])` |changelog']
——
The first part between the |=== is normal AsciiDoc table formatting, which is
easy to understand, but the jsonpathTable2 block macro instruction that formats
the yaml content into the table cells is admittedly difficult to understand. I
haven’t finished documenting the syntax for this, but docs for an earlier
version are here: https://gitlab.com/djencks/asciidoctor-jsonpath.
If someone explains how the current generation works I could try to use that
instead but I don’t know if it will work.
I’m planning to go ahead with this new approach unless there are objections and
an explanation of an alternative.
2. I think it’s implausible to link to git to the exact changelog version for
each release. AFAICT it would require putting the exact blob link into each
subproject yaml entry (or text file, if we stay with the current generation
approach). Instead, I think it’s fine to link to the git HEAD changelog. Since
there are already a variety of git paths used this is already going to b e a
significant effort to maintain.
3. I suggest we remove all non-maintained subprojects from the download page.
They will always be available from the historical releases, but we shouldn’t
be encouraging anyone to use them.
Comments? Suggestions?
Thanks
David Jencks
