PublishMigrationGuide task

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,10 +108,11 @@ asciidoctorj {
 
 // Topical Guides ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-task renderTopicalGuides(type: AsciidoctorTask, group: 'Documentation') {task->
+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')
 	outputDir = new File("$buildDir/asciidoc/topical/html_single")
@@ -126,10 +127,11 @@ task renderTopicalGuides(type: AsciidoctorTask, group: 'Documentation') {task->
 
 // Getting Started Guides (quick starts) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-task renderGettingStartedGuides(type: AsciidoctorTask, group: 'Documentation') {task->
+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 {
@@ -139,7 +141,7 @@ task renderGettingStartedGuides(type: AsciidoctorTask, group: 'Documentation') {
 }
 
 
-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,10 +157,11 @@ task buildTutorialZip(type: Zip) {task->
 
 // User Guide ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-task renderUserGuide(type: AsciidoctorTask, group: 'Documentation') {task->
+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 {
@@ -189,10 +192,12 @@ task renderUserGuide(type: AsciidoctorTask, group: 'Documentation') {task->
 
 // 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,13 +267,12 @@ 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')
 	sources {

local-build-plugins/src/main/java/org/hibernate/orm/docs/DocumentationPublishingPlugin.java

@@ -47,6 +47,13 @@ public class DocumentationPublishingPlugin implements Plugin<Project> {
 				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 );

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

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();
+		RsyncHelper.rsync( jsonFile.get(), url, getProject() );
-
-		getProject().exec( (exec) -> {
-			exec.executable( "rsync" );
-			exec.args( "--port=2222", "-z", jsonPath, url );
-		} );
 	}
 }

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<String> 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<String> 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() );
+	}
+}

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 );
+		} );
+	}
+}

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";

release/release.gradle

@@ -260,8 +260,13 @@ task stageMigrationGuide(type: Copy) {
 
     dependsOn ':documentation:renderMigrationGuide'
 
-    from "${project( ':documentation' ).buildDir}/asciidoc/migration-guide"
+    from project(":documentation").layout.buildDirectory.dir("asciidoc/migration-guide")
-    into "${buildDir}/documentation/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 {