From b1e2412bf2217bed597dc05a6f0eca92d61a4ffc Mon Sep 17 00:00:00 2001 From: Steve Ebersole Date: Sat, 1 Apr 2023 09:33:34 -0500 Subject: [PATCH] PublishMigrationGuide task --- documentation/documentation.gradle | 83 ++++++++++--------- .../docs/DocumentationPublishingPlugin.java | 7 ++ .../orm/docs/GenerateDescriptorTask.java | 6 ++ .../orm/docs/PublishDescriptorTask.java | 9 +- .../orm/docs/PublishMigrationGuide.java | 60 ++++++++++++++ .../org/hibernate/orm/docs/RsyncHelper.java | 22 +++++ .../hibernate/orm/env/HibernateVersion.java | 3 +- release/release.gradle | 11 ++- 8 files changed, 152 insertions(+), 49 deletions(-) create mode 100644 local-build-plugins/src/main/java/org/hibernate/orm/docs/PublishMigrationGuide.java create mode 100644 local-build-plugins/src/main/java/org/hibernate/orm/docs/RsyncHelper.java diff --git a/documentation/documentation.gradle b/documentation/documentation.gradle index 6dfa525e4a..eb2f079613 100644 --- a/documentation/documentation.gradle +++ b/documentation/documentation.gradle @@ -73,7 +73,7 @@ dependencies { if ( project.ormVersion.isSnapshot ) { // only run the ci build tasks for SNAPSHOT versions - task ciBuild( dependsOn: [clean, test] ) + tasks.register('ciBuild') { dependsOn clean, test } tasks.release.enabled false } else { @@ -84,12 +84,12 @@ else { // grouping tasks - declaration, see below for task dependency definitions // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -task buildDocs { +tasks.register('buildDocs') { group 'Documentation' description 'Grouping task for performing all documentation building tasks' } -task buildDocsForPublishing { +tasks.register('buildDocsForPublishing') { group 'Documentation' description 'Grouping task for building all documentation for publishing (release)' } @@ -108,12 +108,13 @@ asciidoctorj { // Topical Guides ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -task renderTopicalGuides(type: AsciidoctorTask, group: 'Documentation') {task-> - description = 'Renders the Topical Guides in HTML format using Asciidoctor.' +tasks.register('renderTopicalGuides', AsciidoctorTask) { task -> + description = 'Renders the Topical Guides in HTML format using Asciidoctor.' tasks.buildDocs.dependsOn task tasks.buildDocsForPublishing.dependsOn task + inputs.property "hibernate-version", project.ormVersion - sourceDir = file( 'src/main/asciidoc/topical' ) + sourceDir = file('src/main/asciidoc/topical') outputDir = new File("$buildDir/asciidoc/topical/html_single") resources { @@ -126,20 +127,21 @@ task renderTopicalGuides(type: AsciidoctorTask, group: 'Documentation') {task-> // Getting Started Guides (quick starts) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -task renderGettingStartedGuides(type: AsciidoctorTask, group: 'Documentation') {task-> - description = 'Renders the Getting Started Guides (quick starts) in HTML format using Asciidoctor.' +tasks.register('renderGettingStartedGuides', AsciidoctorTask) { task -> + description = 'Renders the Getting Started Guides (quick starts) in HTML format using Asciidoctor.' tasks.buildDocs.dependsOn task tasks.buildDocsForPublishing.dependsOn task + inputs.property "hibernate-version", project.ormVersion - sourceDir = file( 'src/main/asciidoc/quickstart/guides' ) - sources { - include 'index.adoc' - } - outputDir = new File("$buildDir/asciidoc/quickstart/html_single") + sourceDir = file('src/main/asciidoc/quickstart/guides') + sources { + include 'index.adoc' + } + outputDir = new File("$buildDir/asciidoc/quickstart/html_single") } -task buildTutorialZip(type: Zip) {task-> +tasks.register('buildTutorialZip', Zip) { task -> from 'src/main/asciidoc/quickstart/tutorials' destinationDirectory = tasks.renderGettingStartedGuides.outputDir archiveFileName = 'hibernate-tutorials.zip' @@ -155,26 +157,27 @@ task buildTutorialZip(type: Zip) {task-> // User Guide ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -task renderUserGuide(type: AsciidoctorTask, group: 'Documentation') {task-> - description = 'Renders the User Guides in HTML format using Asciidoctor.' +tasks.register('renderUserGuide', AsciidoctorTask) { task -> + description = 'Renders the User Guides in HTML format using Asciidoctor.' tasks.buildDocs.dependsOn task tasks.buildDocsForPublishing.dependsOn task + inputs.property "hibernate-version", project.ormVersion - sourceDir = file( 'src/main/asciidoc/userguide' ) - sources { - include 'Hibernate_User_Guide.adoc' - } - outputDir = "$buildDir/asciidoc/userguide/html_single" + sourceDir = file('src/main/asciidoc/userguide') + sources { + include 'Hibernate_User_Guide.adoc' + } + outputDir = "$buildDir/asciidoc/userguide/html_single" attributes linkcss: true, - stylesheet: "css/hibernate.css", - docinfo: 'private', - jpaJavadocUrlPrefix: "https://javaee.github.io/javaee-spec/javadocs/javax/persistence/" + stylesheet: "css/hibernate.css", + docinfo: 'private', + jpaJavadocUrlPrefix: "https://javaee.github.io/javaee-spec/javadocs/javax/persistence/" resources { - from('src/main/asciidoc/userguide/') { - include 'images/**' - } + from('src/main/asciidoc/userguide/') { + include 'images/**' + } from('src/main/style/asciidoctor') { include 'images/**' } @@ -184,15 +187,17 @@ task renderUserGuide(type: AsciidoctorTask, group: 'Documentation') {task-> from('src/main/style/asciidoctor') { include 'js/**' } - } + } } // Integration Guide ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -task renderIntegrationGuide(type: AsciidoctorTask, group: 'Documentation') {task-> +tasks.register( "renderIntegrationGuide", AsciidoctorTask.class, task-> { + group = "Documentation" description = 'Renders the User Guides in HTML format using Asciidoctor.' tasks.buildDocs.dependsOn task tasks.buildDocsForPublishing.dependsOn task + inputs.property "hibernate-version", project.ormVersion sourceDir = file( 'src/main/asciidoc/integrationguide' ) sources { @@ -215,17 +220,18 @@ task renderIntegrationGuide(type: AsciidoctorTask, group: 'Documentation') {task include 'css/**' } } -} +} ) // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ // Migration Guide -task renderMigrationGuide(type: AsciidoctorTask, group: 'Documentation') {task-> +tasks.register( "renderMigrationGuide", AsciidoctorTask.class, task-> { + group = "Documentation" description = 'Renders the Migration Guide in HTML format using Asciidoctor.' - tasks.buildDocs.dependsOn task tasks.buildDocsForPublishing.dependsOn task + inputs.property "hibernate-version", project.ormVersion sourceDir = rootProject.layout.projectDirectory sources { @@ -245,12 +251,12 @@ task renderMigrationGuide(type: AsciidoctorTask, group: 'Documentation') {task-> include 'css/**' } } -} +} ) // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ // ORM Reports -task renderOrmReports { task -> +tasks.register('renderOrmReports') { task -> group 'Documentation' description 'Grouping task for rendering all ORM reports' @@ -261,20 +267,19 @@ task renderOrmReports { task -> tasks.buildDocsForPublishing.dependsOn task } -task renderLoggingReport(type: AsciidoctorTask, group: 'Documentation') { task -> +tasks.register('renderLoggingReport', AsciidoctorTask) { task -> group 'Documentation' description = 'Renders the ORM logging report in HTML format using Asciidoctor.' - dependsOn tasks.generateLoggingReport - tasks.renderOrmReports.dependsOn task + inputs.property "version", project.ormVersion - sourceDir = layout.buildDirectory.dir( 'orm/reports' ) + sourceDir = layout.buildDirectory.dir('orm/reports') sources { include 'logging.adoc' } - outputDir = project.layout.buildDirectory.dir( 'asciidoc/logging' ) + outputDir = project.layout.buildDirectory.dir('asciidoc/logging') attributes linkcss: true, stylesheet: "css/hibernate.css" diff --git a/local-build-plugins/src/main/java/org/hibernate/orm/docs/DocumentationPublishingPlugin.java b/local-build-plugins/src/main/java/org/hibernate/orm/docs/DocumentationPublishingPlugin.java index 06a1d24897..865e3f33d1 100644 --- a/local-build-plugins/src/main/java/org/hibernate/orm/docs/DocumentationPublishingPlugin.java +++ b/local-build-plugins/src/main/java/org/hibernate/orm/docs/DocumentationPublishingPlugin.java @@ -47,6 +47,13 @@ public class DocumentationPublishingPlugin implements Plugin { docPubDsl ); + final PublishMigrationGuide publishMigrationGuideTask = project.getTasks().create( + PublishMigrationGuide.NAME, + PublishMigrationGuide.class, + docPubDsl + ); + publishMigrationGuideTask.getMigrationGuideDirectory().convention( project.getLayout().getBuildDirectory().dir( "asciidoc/migration-guide" ) ); + // todo - incorporate HibernateVersion from `gradle/base-information.gradle` final boolean isSnapshot = project.getVersion().toString().endsWith( "-SNAPSHOT" ); uploadTask.onlyIf( (task) -> !isSnapshot ); diff --git a/local-build-plugins/src/main/java/org/hibernate/orm/docs/GenerateDescriptorTask.java b/local-build-plugins/src/main/java/org/hibernate/orm/docs/GenerateDescriptorTask.java index 59b88912a6..4a7c565af3 100644 --- a/local-build-plugins/src/main/java/org/hibernate/orm/docs/GenerateDescriptorTask.java +++ b/local-build-plugins/src/main/java/org/hibernate/orm/docs/GenerateDescriptorTask.java @@ -31,6 +31,12 @@ public abstract class GenerateDescriptorTask extends DefaultTask { jsonFile = config.getUpdatedJsonFile(); currentlyBuildingFamily = config.getReleaseFamilyIdentifier(); + + getInputs().property( "hibernate-version", currentlyBuildingFamily ); + } + + public ReleaseFamilyIdentifier getCurrentlyBuildingFamily() { + return currentlyBuildingFamily; } @OutputFile diff --git a/local-build-plugins/src/main/java/org/hibernate/orm/docs/PublishDescriptorTask.java b/local-build-plugins/src/main/java/org/hibernate/orm/docs/PublishDescriptorTask.java index 139745c693..f54a9dd9e5 100644 --- a/local-build-plugins/src/main/java/org/hibernate/orm/docs/PublishDescriptorTask.java +++ b/local-build-plugins/src/main/java/org/hibernate/orm/docs/PublishDescriptorTask.java @@ -28,6 +28,8 @@ public abstract class PublishDescriptorTask extends DefaultTask { setGroup( "Release" ); setDescription( "Publishes the documentation publication descriptor (JSON)" ); + getInputs().property( "hibernate-version", getProject().getVersion() ); + docServerUrl = config.getDocDescriptorServerUrl(); jsonFile = config.getUpdatedJsonFile(); } @@ -49,11 +51,6 @@ public abstract class PublishDescriptorTask extends DefaultTask { final String normalizedBase = base.endsWith( "/" ) ? base : base + "/"; final String url = normalizedBase + "_outdated-content/orm.json"; - final String jsonPath = jsonFile.get().getAsFile().getAbsolutePath(); - - getProject().exec( (exec) -> { - exec.executable( "rsync" ); - exec.args( "--port=2222", "-z", jsonPath, url ); - } ); + RsyncHelper.rsync( jsonFile.get(), url, getProject() ); } } diff --git a/local-build-plugins/src/main/java/org/hibernate/orm/docs/PublishMigrationGuide.java b/local-build-plugins/src/main/java/org/hibernate/orm/docs/PublishMigrationGuide.java new file mode 100644 index 0000000000..e11ca970db --- /dev/null +++ b/local-build-plugins/src/main/java/org/hibernate/orm/docs/PublishMigrationGuide.java @@ -0,0 +1,60 @@ +package org.hibernate.orm.docs; + +import javax.inject.Inject; + +import org.gradle.api.DefaultTask; +import org.gradle.api.file.DirectoryProperty; +import org.gradle.api.provider.Provider; +import org.gradle.api.tasks.Input; +import org.gradle.api.tasks.InputDirectory; +import org.gradle.api.tasks.PathSensitive; +import org.gradle.api.tasks.PathSensitivity; +import org.gradle.api.tasks.TaskAction; + +import org.hibernate.orm.ReleaseFamilyIdentifier; + +/** + * @author Steve Ebersole + */ +public abstract class PublishMigrationGuide extends DefaultTask { + public static final String NAME = "publishMigrationGuide"; + + private final Provider docServerUrl; + + private final ReleaseFamilyIdentifier currentlyBuildingFamily; + private final DirectoryProperty migrationGuideDirectory; + + @Inject + public PublishMigrationGuide(DocumentationPublishing config) { + setGroup( "Release" ); + setDescription( "Publishes the migration-guide associated with the current branch. " + + "Intended for incremental publishing of the guide for corrections, etc. without doing a full release. " + + "Note that this is not needed when doing a release as the migration-guide is published as part of that workflow." ); + + getInputs().property( "hibernate-version", getProject().getVersion() ); + + docServerUrl = config.getDocServerUrl(); + currentlyBuildingFamily = config.getReleaseFamilyIdentifier(); + migrationGuideDirectory = getProject().getObjects().directoryProperty(); + } + + @InputDirectory + @PathSensitive(PathSensitivity.RELATIVE) + public DirectoryProperty getMigrationGuideDirectory() { + return migrationGuideDirectory; + } + + @Input + public Provider getDocServerUrl() { + return docServerUrl; + } + + @TaskAction + public void uploadMigrationGuide() { + final String base = docServerUrl.get(); + final String normalizedBase = base.endsWith( "/" ) ? base : base + "/"; + final String url = normalizedBase + currentlyBuildingFamily.toExternalForm() + "/migration-guide/"; + + RsyncHelper.rsync( migrationGuideDirectory.get(), url, getProject() ); + } +} diff --git a/local-build-plugins/src/main/java/org/hibernate/orm/docs/RsyncHelper.java b/local-build-plugins/src/main/java/org/hibernate/orm/docs/RsyncHelper.java new file mode 100644 index 0000000000..2cc8a0b52e --- /dev/null +++ b/local-build-plugins/src/main/java/org/hibernate/orm/docs/RsyncHelper.java @@ -0,0 +1,22 @@ +package org.hibernate.orm.docs; + +import org.gradle.api.Project; +import org.gradle.api.file.FileSystemLocation; + +/** + * Helper for performing rsync system commands, mainly used to centralize + * the command options + * + * @author Steve Ebersole + */ +public class RsyncHelper { + public static void rsync( + FileSystemLocation source, + String targetUrl, + Project project) { + project.exec( (exec) -> { + exec.executable( "rsync" ); + exec.args( "--port=2222", "-avz", source.getAsFile().getAbsolutePath(), targetUrl ); + } ); + } +} diff --git a/local-build-plugins/src/main/java/org/hibernate/orm/env/HibernateVersion.java b/local-build-plugins/src/main/java/org/hibernate/orm/env/HibernateVersion.java index 9a93fba7d7..b372c4c094 100644 --- a/local-build-plugins/src/main/java/org/hibernate/orm/env/HibernateVersion.java +++ b/local-build-plugins/src/main/java/org/hibernate/orm/env/HibernateVersion.java @@ -10,6 +10,7 @@ import java.io.File; import java.io.FileInputStream; import java.io.IOException; import java.io.InputStream; +import java.io.Serializable; import java.util.Properties; import java.util.function.Consumer; @@ -18,7 +19,7 @@ import org.gradle.api.Project; /** * @author Steve Ebersole */ -public class HibernateVersion { +public class HibernateVersion implements Serializable { public static final String EXT_KEY = "ormVersion"; public static final String VERSION_KEY = "releaseVersion"; public static final String RELATIVE_FILE = "gradle/version.properties"; diff --git a/release/release.gradle b/release/release.gradle index 140a77849f..ae899d6a38 100644 --- a/release/release.gradle +++ b/release/release.gradle @@ -260,8 +260,13 @@ task stageMigrationGuide(type: Copy) { dependsOn ':documentation:renderMigrationGuide' - from "${project( ':documentation' ).buildDir}/asciidoc/migration-guide" - into "${buildDir}/documentation/migration-guide" + from project(":documentation").layout.buildDirectory.dir("asciidoc/migration-guide") + into layout.buildDirectory.dir("documentation/migration-guide") +} + +tasks.named( "publishMigrationGuide" ).configure { + dependsOn stageMigrationGuide + migrationGuideDirectory = project.layout.buildDirectory.dir("documentation/migration-guide") } task stageOrmReports { @@ -701,4 +706,4 @@ static String determineReleaseTag(String releaseVersion) { return releaseVersion.endsWith( '.Final' ) ? releaseVersion.replace( ".Final", "" ) : releaseVersion; -} \ No newline at end of file +}