Apache
/
lucene
mirror of https://github.com/apache/lucene.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' of https://gitbox.apache.org/repos/asf/lucene-solr

This commit is contained in:
Uwe Schindler 2020-09-03 17:51:20 +02:00
parent 469d742384 0ce6de61e8
commit 5d4487d707
1 changed files with 12 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
solr/solr-ref-guide/src/meta-docs/publish.adoc
View File

@ -30,32 +30,31 @@ In order to build the Ref Guide, you must have the following:
* You have checked out the Lucene/Solr source code on the machine you will be doing the release from. * You have checked out the Lucene/Solr source code on the machine you will be doing the release from.
* You have Subversion installed. This is needed for committing the HTML files to the production website repo. * You have Subversion installed. This is needed for committing the HTML files to the production website repo.
* You have installed Ruby and several gems described in the README file located at `solr/solr-ref-guide/README.adoc` in your Lucene/Solr checkout.
* All builds must be done from the release branch the Guide is for. * All builds must be done from the release branch the Guide is for.
NOTE: Builds are available via https://builds.apache.org/view/L/view/Lucene/[Jenkins] for several branches. However, these HTML pages will have the `DRAFT` status noted in them and are not suitable for final production publishing. NOTE: Builds are available via https://builds.apache.org/view/L/view/Lucene/[Jenkins] for several branches. However, these HTML pages will have the `DRAFT` status noted in them and are not suitable for final production publishing.
All dependencies for the build will be installed by Gradle, no local dependencies are required.
== Build the DRAFT Guide == Build the DRAFT Guide
The build process generates the page hierarchy and builds the HTML pages with custom templates the Lucene/Solr project has defined. The build process generates the page hierarchy and builds the HTML pages with custom templates the Lucene/Solr project has defined.
To build the HTML: To build the HTML, from the top level of the project, run:
. Navigate to `./solr/solr-ref-guide`, where the Guide's `build.xml` is located.
. Run:
+
[source,bash] [source,bash]
$ gradlew clean buildSite $ gradlew clean solr:solr-ref-guide:buildSite
+
This will produce pages with a DRAFT watermark across them. While these are fine for initial DRAFT publication, see the section <<Publish the Final Guide>> for steps to produce final production-ready HTML pages. This will produce pages with a DRAFT watermark across them. While these are fine for initial DRAFT publication, see the section <<Publish the Final Guide>> for steps to produce final production-ready HTML pages.
. The resulting Guide will be in `solr/build/solr-ref-guide`. The HTML files themselves will be in `solr/build/solr-ref-guide/html-site`.
The resulting Guide will be in `solr/solr-ref-guide/build`. The HTML files themselves will be in `solr/solr-ref-guide/build/html-site`.
== Upload to the Website == Upload to the Website
Push the Guide directly to production via Subversion `import` from where you built it. Push the Guide directly to production via Subversion `import` from where you built it.
[source,bash] [source,bash]
svn -m "Add Ref Guide for Solr 7.7" import <checkoutroot>/solr/build/solr-ref-guide/html-site https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/guide/7_7 svn -m "Add Ref Guide for Solr 7.7" import <checkoutroot>/solr/solr-ref-guide/build/html-site https://svn.apache.org/repos/infra/websites/production/lucene/content/solr/guide/7_7
Confirm you can browse to Guide manually by going to the new URL. For example: Confirm you can browse to Guide manually by going to the new URL. For example:
https://lucene.apache.org/solr/guide/7_7 https://lucene.apache.org/solr/guide/7_7
@ -73,11 +72,11 @@ Since the Guide has already been uploaded to SVN, you need to overwrite the exis
Build the Guide locally with a parameter for the Guide version. This requires the same <<Pre-Requisites,pre-requisites>> from above. Build the Guide locally with a parameter for the Guide version. This requires the same <<Pre-Requisites,pre-requisites>> from above.
[source,bash] [source,bash]
$gradlew clean buildSite -Dsolr-guide-version=X.Y $gradlew clean solr:solr-ref-guide:buildSite -PsolrGuideVersion=X.Y
where `X.Y` is the version you want to publish (i.e., `7.7`). where `X.Y` is the version you want to publish (i.e., `7.7`).
IMPORTANT: The `-Dsolr-guide-version` system property is optional if you build drafts locally or as pre-publication DRAFTs (i.e., not for publication). By default the build system uses the `lucene/version.properties` file in the current branch and assumes this is a `DRAFT` build which will have a DRAFT watermark and other labels on the pages. Including the `-Dsolr-guide-version` system property ensures the DRAFT watermark and labels are removed from the HTML files. IMPORTANT: The `-PsolrGuideVersion` system property is optional if you build drafts locally or as pre-publication DRAFTs (i.e., not for publication). By default the build system uses the `build.gradle` file in the current branch to identify the version and assumes this is a `DRAFT` build which will have a DRAFT watermark and other labels on the pages. Including the `-PsolrGuideVersion` system property ensures the DRAFT watermark and labels are removed from the HTML files.
*Pull Production Repo and Upload New Files* *Pull Production Repo and Upload New Files*
@ -88,7 +87,7 @@ $ svn co https://svn.apache.org/repos/infra/websites/production/lucene/content/s
+ +
* This command checks out the Guide version directory into a local subdirectory with the same name as the version (such as "7_7"). You can provide a better name locally if you prefer by adding it to the end of the command shown above. * This command checks out the Guide version directory into a local subdirectory with the same name as the version (such as "7_7"). You can provide a better name locally if you prefer by adding it to the end of the command shown above.
* Don't shortcut this and download the whole production website. It will take an incredibly long time and that will feel like _forever_. * Don't shortcut this and download the whole production website. It will take an incredibly long time and that will feel like _forever_.
. Copy the files from the build location to the checked out Guide directory. For example, if we needed to replace the Guide for Solr 7.7, we'd do `cp -r ./solr/build/solr-ref-guide/html-site 7_7/.` . Copy the files from the build location to the checked out Guide directory. For example, if we needed to replace the Guide for Solr 7.7, we'd do `cp -r ./solr/solr-ref-guide/build/html-site 7_7/.`
. Use `svn status` to see the files modified. If there are any pages added or deleted, use `svn add <file>` or `svn rm <file>` as needed. . Use `svn status` to see the files modified. If there are any pages added or deleted, use `svn add <file>` or `svn rm <file>` as needed.
. Commit the changes: `svn commit -m "Update production 7.7 Ref Guide"` . Commit the changes: `svn commit -m "Update production 7.7 Ref Guide"`
@ -98,7 +97,7 @@ Spot-check a few pages to verify that the DRAFT watermark is gone, and also
that Solr Javadocs link back to Lucene's correctly (the UpdateRequestProcessor that Solr Javadocs link back to Lucene's correctly (the UpdateRequestProcessor
page has a lot of Javadoc links). page has a lot of Javadoc links).
=== Make a link to the new Version from website === Link to the New Version from Solr Website
The only edit we need to do in the website itself is adding a link to the latest guide to /solr/guide. The only edit we need to do in the website itself is adding a link to the latest guide to /solr/guide.