You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@felix.apache.org by David Jencks <da...@gmail.com> on 2021/06/29 20:59:03 UTC
New website question #2 - downloads page (3 part question/proposal)
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
Re: New website question #2 - downloads page (3 part question/proposal)
Posted by Pierre De Rop <pi...@gmail.com>.
David,
I forgot to say that there are some specific adaptations we made for
DependencyManager in [1], see:
...
* if ($title eq "Dependency Manager 4") { ${$target} .=
"|$title|" . changelogLink("$artifact", "$version",
$changelog) . " | " .
downloadLink("$artifact-$version$classifier.zip", "zip")
. " | " .
downloadLink("$artifact-$version-$srcClassifier.zip", "zip")
. "|\n"; }* else {
${$target} .= "|$title|"
. changelogLink("$artifact", "$version", $changelog)
. " | "
. downloadLink("$artifact-$version$classifier.jar",
"jar")
. " | "
.
downloadLink("$artifact-$version-$srcClassifier.tar.gz", "tar.gz")
. " "
.
downloadLink("$artifact-$version-$srcClassifier.zip", "zip")
. "|\n";
}
...
If this is causing any problems for you, for the moment you can ignore the
"if" for Dependency Manager 4.
Indeed, this hack was required at the time we switch to bndtools, but I
plan to rework the DM project soon in order to use the bnd-maven-plugin,
that will then allow to remove the DM adaptations in [1].
[1] http://svn.apache.org/repos/asf/felix/site/trunk/lib/view.pm
On Wed, Jun 30, 2021 at 12:05 AM Pierre De Rop <pi...@gmail.com>
wrote:
> Hi David,
>
> I think that the download page is generated using [1]. The view.pm script
> then parses [2], but I don't know how and who is invoking the view.pm
> script.
>
> [1] http://svn.apache.org/repos/asf/felix/site/trunk/lib/view.pm
> [2]
> http://svn.apache.org/repos/asf/felix/site/trunk/content/downloads.list
>
> regards
> /pierre
>
> On Tue, Jun 29, 2021 at 10:59 PM David Jencks <da...@gmail.com>
> wrote:
>
>> 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
>>
>>
Re: New website question #2 - downloads page (3 part question/proposal)
Posted by Pierre De Rop <pi...@gmail.com>.
Hi David,
I think that the download page is generated using [1]. The view.pm script
then parses [2], but I don't know how and who is invoking the view.pm
script.
[1] http://svn.apache.org/repos/asf/felix/site/trunk/lib/view.pm
[2] http://svn.apache.org/repos/asf/felix/site/trunk/content/downloads.list
regards
/pierre
On Tue, Jun 29, 2021 at 10:59 PM David Jencks <da...@gmail.com>
wrote:
> 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
>
>