[
https://issues.apache.org/jira/browse/LUCENE-9495?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17188853#comment-17188853
]
Chris M. Hostetter edited comment on LUCENE-9495 at 9/1/20, 11:09 PM:
----------------------------------------------------------------------
{quote}To accomplish this, the guide has long used a parameter
{{solr-guide-version}} to indicate when a build for the Ref Guide _should not_
be considered a draft. With the Gradle build, this no longer works. (I thought
I'd tested this, but either I missed it or it broke at some point in between.)
{quote}
IIUC it _does_ seem to work, but:
* it's been renamed (probably to be more "gradle-esque" ?) using camel case:
{{solrGuideVersion}}
* it has to be specified using '{{-P}}' (which is evidently the gradle way of
setting _project_ properties on the command line
(and it looks like this info wasn't fully updated in {{how-to-contribute.adoc}}
?)
So on master you can do...
{noformat}
hossman@slate:~/lucene/dev/solr/solr-ref-guide [j11] [master] $ gradle buildSite
Using gradle at '/home/hossman/lucene/dev/gradlew' to run buildfile
'/home/hossman/lucene/dev/solr/solr-ref-guide/build.gradle':
> Task :solr:solr-ref-guide:setupLazyProps
Building ref guide with:
solr-root-path -> ../../../../solr/
solr-guide-draft-status -> DRAFT
solr-guide-version -> 9.0-DRAFT
solr-guide-version-path -> 9_0-DRAFT
solr-docs-version -> 9.0
javadoc.link -> https://docs.oracle.com/en/java/javase/11/docs/api/
java-javadocs -> https://docs.oracle.com/en/java/javase/11/docs/api/
solr-javadocs -> https://lucene.apache.org/solr/9_0_0/
html-solr-javadocs -> https://lucene.apache.org/solr/9_0_0/
lucene-javadocs -> https://lucene.apache.org/core/9_0_0/
html-lucene-javadocs -> https://lucene.apache.org/core/9_0_0/
...
{noformat}
...to get the "default" version numbers and DRAFT status info, or you can do...
{noformat}
hossman@slate:~/lucene/dev/solr/solr-ref-guide [j11] [master] $ gradle
buildSite -PsolrGuideVersion=9.0
Using gradle at '/home/hossman/lucene/dev/gradlew' to run buildfile
'/home/hossman/lucene/dev/solr/solr-ref-guide/build.gradle':
> Task :solr:solr-ref-guide:setupLazyProps
Building ref guide with:
solr-root-path -> ../../../../solr/
solr-guide-draft-status ->
solr-guide-version -> 9.0
solr-guide-version-path -> 9_0
solr-docs-version -> 9.0
javadoc.link -> https://docs.oracle.com/en/java/javase/11/docs/api/
java-javadocs -> https://docs.oracle.com/en/java/javase/11/docs/api/
solr-javadocs -> https://lucene.apache.org/solr/9_0_0/
html-solr-javadocs -> https://lucene.apache.org/solr/9_0_0/
lucene-javadocs -> https://lucene.apache.org/core/9_0_0/
html-lucene-javadocs -> https://lucene.apache.org/core/9_0_0/
...
{noformat}
...to explicitly set the version and prevent the DRAFT status.
----
{quote}Beyond getting this to work, I think it's worth a discussion (separate
Jira?) about whether we can simplify it. Maybe just a parameter
ref-guide-draft=false would be sufficient? We might also reconsider the
variations of versions in the Ref Guide params and whether we really need them
(solr-guide-version, solr-docs-version).
{quote}
We can certainly simplify a *LOT* of this – most of the complexity here comes
from when we had "official releases" of the ref-guide in PDF as well as HTML,
and wanted/needed to be able to:
* have a ref-guide version that was based on the major.minor solr version
** but had an independent and optional bugfix value...
*** because we didn't do ref-guide releases for every solr bugfix
*** BUT: we wanted to have the ability to to "bugfix" releases of the ref
guide if it had egregious errors: (ie: refguide version 8.1 might have been
followed y ref guide version 8.1.1 even if there was never a solr 8.1.1)
* link to version specific javadocs
** using absolute URLs in the PDF
** BUT using relative URLs from the html that we would host on the site
A lot of this was spelled out in the build.xml comments, but that info
evidently wasn't preserved in the creation of build.gradle...
{noformat}
<loadresource property="solr-docs-version">
<!-- NOTE: this is specifically only the "major.minor", it does not include
the ".bugfix"
This is because we (currently) only release the guide for minor
versions.
-->
...
</loadresource>
<loadresource property="solr-docs-version-path">
<!-- NOTE: This is the ${solr-docs-version} as a path suitbale for linking
to javadocs -->
...
</loadresource>
<!-- NOTE: ${solr-guide-version} is the version of this ref-guide.
By default, we assume this is the same as ${solr-docs-version} with a
"-DRAFT" suffix
When releasing, specify an explicit value of this property on the
command line.
NOTE: the ${solr-guide-version} used *may* be different from the version
of Solr the guide
covers if we decide to do a bug-fix release of the ref-guide
Examples: (assume branch_6_1 where version=6.1.SOMETHING)
Basic nightly/local build of the 6.1 guide...
=> ant build-site
Official build of the 6.1 guide...
=> ant build-site -Dsolr-guide-version=6.1
Release of a "6.1.1" ref guide, correcting some serious error in the docs
(even if there is no 6.1.1 version - or if we've already released up to
6.1.5 - of Solr itself)
=> ant build-site -Dsolr-guide-version=6.1.1
-->
<property name="solr-guide-version" value="${solr-docs-version}-DRAFT" />
<condition property="solr-guide-draft-status" value="" else="DRAFT">
<matches pattern="^\d+\.\d+(|\.\d+)$" string="${solr-guide-version}" />
</condition>
<loadresource property="solr-guide-version-path">
<!-- NOTE: This is the ${solr-guide-version} as a path suitable for use
publishing the HTML -->
...
</loadresource>
{noformat}
was (Author: hossman):
{quote}To accomplish this, the guide has long used a parameter
{{solr-guide-version}} to indicate when a build for the Ref Guide _should not_
be considered a draft. With the Gradle build, this no longer works. (I thought
I'd tested this, but either I missed it or it broke at some point in between.)
{quote}
IIUC it _does_ seem to work, but:
* it's been renamed (probably to be more "gradle-esque" ?) using camel case
* it has to be specified using '{{-P}}' (which is evidently the gradle way of
setting _project_ properties on the command line
(and it looks like this info wasn't fully updated in {{how-to-contribute.adoc}}
?)
So on master you can do...
{noformat}
hossman@slate:~/lucene/dev/solr/solr-ref-guide [j11] [master] $ gradle buildSite
Using gradle at '/home/hossman/lucene/dev/gradlew' to run buildfile
'/home/hossman/lucene/dev/solr/solr-ref-guide/build.gradle':
> Task :solr:solr-ref-guide:setupLazyProps
Building ref guide with:
solr-root-path -> ../../../../solr/
solr-guide-draft-status -> DRAFT
solr-guide-version -> 9.0-DRAFT
solr-guide-version-path -> 9_0-DRAFT
solr-docs-version -> 9.0
javadoc.link -> https://docs.oracle.com/en/java/javase/11/docs/api/
java-javadocs -> https://docs.oracle.com/en/java/javase/11/docs/api/
solr-javadocs -> https://lucene.apache.org/solr/9_0_0/
html-solr-javadocs -> https://lucene.apache.org/solr/9_0_0/
lucene-javadocs -> https://lucene.apache.org/core/9_0_0/
html-lucene-javadocs -> https://lucene.apache.org/core/9_0_0/
...
{noformat}
...to get the "default" version numbers and DRAFT status info, or you can do...
{noformat}
hossman@slate:~/lucene/dev/solr/solr-ref-guide [j11] [master] $ gradle
buildSite -PsolrGuideVersion=9.0
Using gradle at '/home/hossman/lucene/dev/gradlew' to run buildfile
'/home/hossman/lucene/dev/solr/solr-ref-guide/build.gradle':
> Task :solr:solr-ref-guide:setupLazyProps
Building ref guide with:
solr-root-path -> ../../../../solr/
solr-guide-draft-status ->
solr-guide-version -> 9.0
solr-guide-version-path -> 9_0
solr-docs-version -> 9.0
javadoc.link -> https://docs.oracle.com/en/java/javase/11/docs/api/
java-javadocs -> https://docs.oracle.com/en/java/javase/11/docs/api/
solr-javadocs -> https://lucene.apache.org/solr/9_0_0/
html-solr-javadocs -> https://lucene.apache.org/solr/9_0_0/
lucene-javadocs -> https://lucene.apache.org/core/9_0_0/
html-lucene-javadocs -> https://lucene.apache.org/core/9_0_0/
...
{noformat}
...to explicitly set the version and prevent the DRAFT status.
----
{quote}Beyond getting this to work, I think it's worth a discussion (separate
Jira?) about whether we can simplify it. Maybe just a parameter
ref-guide-draft=false would be sufficient? We might also reconsider the
variations of versions in the Ref Guide params and whether we really need them
(solr-guide-version, solr-docs-version).
{quote}
We can certainly simplify a *LOT* of this – most of the complexity here comes
from when we had "official releases" of the ref-guide in PDF as well as HTML,
and wanted/needed to be able to:
* have a ref-guide version that was based on the major.minor solr version
** but had an independent and optional bugfix value...
*** because we didn't do ref-guide releases for every solr bugfix
*** BUT: we wanted to have the ability to to "bugfix" releases of the ref
guide if it had egregious errors: (ie: refguide version 8.1 might have been
followed y ref guide version 8.1.1 even if there was never a solr 8.1.1)
* link to version specific javadocs
** using absolute URLs in the PDF
** BUT using relative URLs from the html that we would host on the site
A lot of this was spelled out in the build.xml comments, but that info
evidently wasn't preserved in the creation of build.gradle...
{noformat}
<loadresource property="solr-docs-version">
<!-- NOTE: this is specifically only the "major.minor", it does not include
the ".bugfix"
This is because we (currently) only release the guide for minor
versions.
-->
...
</loadresource>
<loadresource property="solr-docs-version-path">
<!-- NOTE: This is the ${solr-docs-version} as a path suitbale for linking
to javadocs -->
...
</loadresource>
<!-- NOTE: ${solr-guide-version} is the version of this ref-guide.
By default, we assume this is the same as ${solr-docs-version} with a
"-DRAFT" suffix
When releasing, specify an explicit value of this property on the
command line.
NOTE: the ${solr-guide-version} used *may* be different from the version
of Solr the guide
covers if we decide to do a bug-fix release of the ref-guide
Examples: (assume branch_6_1 where version=6.1.SOMETHING)
Basic nightly/local build of the 6.1 guide...
=> ant build-site
Official build of the 6.1 guide...
=> ant build-site -Dsolr-guide-version=6.1
Release of a "6.1.1" ref guide, correcting some serious error in the docs
(even if there is no 6.1.1 version - or if we've already released up to
6.1.5 - of Solr itself)
=> ant build-site -Dsolr-guide-version=6.1.1
-->
<property name="solr-guide-version" value="${solr-docs-version}-DRAFT" />
<condition property="solr-guide-draft-status" value="" else="DRAFT">
<matches pattern="^\d+\.\d+(|\.\d+)$" string="${solr-guide-version}" />
</condition>
<loadresource property="solr-guide-version-path">
<!-- NOTE: This is the ${solr-guide-version} as a path suitable for use
publishing the HTML -->
...
</loadresource>
{noformat}
> Ref Guide gradle buildSite ignores version parameter
> ----------------------------------------------------
>
> Key: LUCENE-9495
> URL: https://issues.apache.org/jira/browse/LUCENE-9495
> Project: Lucene - Core
> Issue Type: Bug
> Components: general/build
> Reporter: Cassandra Targett
> Priority: Major
>
> All Ref Guide builds by default are built as drafts. A DRAFT watermark is
> inserted on to every page, a special header is added to the side navigation,
> and the footer version includes the word "-DRAFT".
> To accomplish this, the guide has long used a parameter
> {{solr-guide-version}} to indicate when a build for the Ref Guide _should
> not_ be considered a draft. With the Gradle build, this no longer works. (I
> thought I'd tested this, but either I missed it or it broke at some point in
> between.)
> [~hossman] set this up several years ago, so cc'ing him here so he can take a
> look and see why the logic would stop working now.
> Links:
> Ref Guide {{build.gradle}} that determines Guide version:
> https://github.com/apache/lucene-solr/blob/master/solr/solr-ref-guide/build.gradle#L128
> Ant {{build.xml}} the above was adapted from:
> https://github.com/apache/lucene-solr/blob/branch_8x/solr/solr-ref-guide/build.xml#L70
>
> Beyond getting this to work, I think it's worth a discussion (separate Jira?)
> about whether we can simplify it. Maybe just a parameter
> {{ref-guide-draft=false}} would be sufficient? We might also reconsider the
> variations of versions in the Ref Guide params and whether we really need
> them ({{solr-guide-version}}, {{solr-docs-version}}).
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscr...@lucene.apache.org
For additional commands, e-mail: issues-h...@lucene.apache.org
