HHH-16962 - General documentation improvements

https://hibernate.atlassian.net/browse/HHH-16962

documentation/documentation.gradle

@@ -282,10 +282,23 @@ def renderTopicalGuidesTask = tasks.register( 'renderTopicalGuides', Asciidoctor
 
 def gettingStartedGuideHtmlDir = layout.buildDirectory.dir( "asciidoc/quickstart/html_single" )
 
+def buildTutorialZipTask = tasks.register( 'buildTutorialZip', Zip ) { task ->
+	from 'src/main/asciidoc/quickstart/tutorials'
+	destinationDirectory.set( gettingStartedGuideHtmlDir )
+	archiveFileName = 'hibernate-tutorials.zip'
+	expand(
+			version: project.version,
+			slf4j: "2.0.7",
+			junit: testLibs.versions.junit4.get(),
+			h2: dbLibs.versions.h2.get()
+	)
+}
+
 def renderGettingStartedGuideHtmlTask = tasks.register( 'renderGettingStartedGuideHtmlTask', AsciidoctorTask ) { task ->
 	group = "Documentation"
 	description = 'Renders the Getting Started Guides (quickstarts) in HTML format using Asciidoctor.'
 	inputs.property "hibernate-version", project.ormVersion
+	finalizedBy buildTutorialZipTask
 
 	sourceDir = file( 'src/main/asciidoc/quickstart/guides' )
 	sources 'index.adoc'
@@ -325,18 +338,6 @@ def renderGettingStartedGuidePdfTask = tasks.register( 'renderGettingStartedGuid
 	attributes jpaJavadocUrlPrefix: "https://javaee.github.io/javaee-spec/javadocs/javax/persistence/"
 }
 
-def buildTutorialZipTask = tasks.register( 'buildTutorialZip', Zip ) { task ->
-	from 'src/main/asciidoc/quickstart/tutorials'
-	destinationDirectory.set( gettingStartedGuideHtmlDir )
-	archiveFileName = 'hibernate-tutorials.zip'
-	expand(
-			version: project.version,
-			slf4j: "2.0.7",
-			junit: testLibs.versions.junit4.get(),
-			h2: dbLibs.versions.h2.get()
-	)
-}
-
 def renderGettingStartedGuidesTask = tasks.register( 'renderGettingStartedGuides' ) { task ->
 	task.group = "Documentation"
 	task.description = 'Renders the Getting Started Guide in all formats, as well as the acccompanying tutorial zip.'
@@ -658,15 +659,28 @@ def renderIntegrationGuidesTask = tasks.register( "renderIntegrationGuides" ) {
 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 // Migration Guide
 
-def renderMigrationGuideTask = tasks.register( "renderMigrationGuide", AsciidoctorTask ) { task ->
+def migrationGuideSourceStagingDir = layout.buildDirectory.dir( "tmp/asciidoc/migration-guide" )
+
+def copyMigrationGuideTask = tasks.register( "copyMigrationGuide", Copy ) {task ->
 	group = "Documentation"
-	description = 'Renders the Migration Guide in HTML format using Asciidoctor.'
+	description = "Copies migration-guide.adoc in preparation for rendering."
 
 	inputs.property "hibernate-version", project.ormVersion
 
-	sources {
+	from rootProject.layout.projectDirectory.file( "migration-guide.adoc" )
-		include rootProject.layout.projectDirectory.file( 'migration-guide.adoc' ).asFile.canonicalPath
+	into migrationGuideSourceStagingDir
-	}
+}
+
+def renderMigrationGuideTask = tasks.register( "renderMigrationGuide", AsciidoctorTask ) { task ->
+	group = "Documentation"
+	description = "Renders the Migration Guide in HTML format using Asciidoctor."
+
+	dependsOn copyMigrationGuideTask
+	inputs.property "hibernate-version", project.ormVersion
+
+	sourceDir = migrationGuideSourceStagingDir
+
+	outputDir = project.layout.buildDirectory.dir( 'asciidoc/migration-guide' )
 
 	attributes linkcss: true,
 			   stylesheet: "css/hibernate.css"

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

@@ -60,7 +60,7 @@ public class DocumentationPublishingPlugin implements Plugin<Project> {
 				(task) -> {
 					task.getCurrentlyBuildingFamily().convention( docPubDsl.getReleaseFamilyIdentifier() );
 					task.getDocServerUrl().convention( docPubDsl.getDocServerUrl() );
-					task.getMigrationGuideDirectory().convention( project.getLayout().getBuildDirectory().dir( "asciidoc/migration-guide" ) );
+					task.getMigrationGuideDirectory().convention( project.getLayout().getBuildDirectory().dir( "documentation/migration-guide" ) );
 				}
 		);
 

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

@@ -54,6 +54,8 @@ public abstract class PublishMigrationGuide extends DefaultTask {
 		return docServerUrl;
 	}
 
+
+	@Input
 	public Property<ReleaseFamilyIdentifier> getCurrentlyBuildingFamily() {
 		return currentlyBuildingFamily;
 	}

local-build-plugins/src/main/java/org/hibernate/orm/post/DeprecationReportTask.java

@@ -32,7 +32,7 @@ public class DeprecationReportTask extends AbstractJandexAwareTask {
 	public DeprecationReportTask() {
 		setDescription( "Generates a report for things considered deprecated" );
 		reportFile = getProject().getObjects().fileProperty();
-		reportFile.convention( getProject().getLayout().getBuildDirectory().file( "orm/reports/deprecating.txt" ) );
+		reportFile.convention( getProject().getLayout().getBuildDirectory().file( "orm/reports/deprecated.txt" ) );
 	}
 
 	@Override

release/src/release/announcement-template.adoc

@@ -1,11 +1,14 @@
-= Hibernate {{version-here}}
+:family: 6.3
+:version: 6.3.0.Final
+
+= Hibernate {version}
 Steve Ebersole
 :awestruct-tags: ["Hibernate ORM", "Releases"]
 :awestruct-layout: blog-post
-:version: {{version-here}}
+:docs-url: https://docs.jboss.org/hibernate/orm/{family}
-:docs-url: https://docs.jboss.org/hibernate/orm/{version}
 :javadocs-url: {docs-url}/javadocs
 :migration-guide-url: {docs-url}/migration-guide/migration-guide.html
+:intro-guide-url: {docs-url}/introduction/html_single/Hibernate_Introduction.html
 :user-guide-url: {docs-url}/userguide/html_single/Hibernate_User_Guide.html
 
 // Text ...
@@ -15,15 +18,17 @@ Steve Ebersole
 
 For additional details, see:
 
-- the link:{user-guide-url}[User Guide]
-- the link:{migration-guide-url}[Migration Guide]
 - the https://hibernate.org/orm/releases/6.0/[release page]
+- the link:{migration-guide-url}[Migration Guide]
+- the link:{intro-guide-url}[Hibernate 6 Introduction]
+- the link:{user-guide-url}[User Guide]
 
 See also the following resources related to supported APIs:
 
-- the link:{docs-url}/incubating/incubating.txt[incubating API report] - `@Incubating`
+- the https://hibernate.org/community/compatibility-policy/[compatibility policy]
-- the link:{docs-url}/deprecated/deprecated.txt[deprecated API report] - `@Deprecated` + `@Remove`
+- the link:{docs-url}/incubating/incubating.txt[incubating API report] (`@Incubating`)
-- the link:{docs-url}/internals/internal.txt[internal API report] - internal packages, `@Internal`
+- the link:{docs-url}/deprecated/deprecated.txt[deprecated API report] (`@Deprecated` + `@Remove`)
+- the link:{docs-url}/internals/internal.txt[internal API report] (internal packages, `@Internal`)
 
 Visit the https://hibernate.org/community/[website] for details on getting in touch with us.