release announcement, doc artifacts

design/working/6.0-posts.adoc

@@ -37,7 +37,7 @@ from the removal of deprecated stuff.  There are a few one-off changes that brea
 source compatibility; these are covered in the link:{migration-guide-url}[migration guide].
 
 One specific change to note is that many of these contracts have been better defined with type
-parameters.  Theses where inconsistently and sometimes poorly defined in previous versions.
+parameters.  Theses were inconsistently and sometimes poorly defined in previous versions.
 
 Quite a few SPI contracts have changed to support many of the topics discussed here as well as in
 the link:{migration-guide-url}[migration guide].  Many will also be the subject of the mentioned
@@ -219,3 +219,32 @@ which is why Hibernate  had so many version-specific subclasses.
 
 6.0 changes the way Dialects are created to allow them to initialize themselves based on the
 version of the database/driver being used.
+
+
+[[incubating]]
+== @Incubating
+
+6.0 also introduces a new `@Incubating` annotation which is intended to notify users that
+a particular contract may change in the future.  These are typically new contracts which
+we may need to change in response to additional use cases or clarification of existing use cases.
+
+Think of it as a "use at your own risk" kind of notice.  Obviously we will strive to not change
+such contracts, but this gives us the flexibility to do so if needed and communicating that this
+could potentially happen to the user.
+
+Sometimes settings are considered incubating.  These are indicated by `@Incubating` on the
+corresponding `org.hibernate.cfg.AvailableSettings` field and are also logged using the
+`org.hibernate.orm.incubating` category.
+
+We also generate a <<documentation-artifacts,report>>.
+
+
+[[documentation-artifacts]]
+== New documentation artifacts
+
+Starting in 6.0 we also now publish additional documentation artifacts, such as:
+
+- The link:{migration-guide-url}[Migration Guide]
+- The generated link:{docs-url}/logging/logging.html[logging] report
+- The generated link:{docs-url}/incubating/incubating.txt[incubation] report
+- The generated link:{docs-url}/internals/internal.txt[internals] report

documentation/documentation.gradle

@@ -159,7 +159,7 @@ task renderUserGuide(type: AsciidoctorTask, group: 'Documentation') {task->
     sources {
         include 'Hibernate_User_Guide.adoc'
     }
-    outputDir = new File("$buildDir/asciidoc/userguide/html_single")
+    outputDir = "$buildDir/asciidoc/userguide/html_single"
 
 	attributes linkcss: true,
 			   stylesheet: "css/hibernate.css",
@@ -194,7 +194,7 @@ task renderIntegrationGuide(type: AsciidoctorTask, group: 'Documentation') {task
 		include 'Hibernate_Integration_Guide.adoc'
 	}
 
-	outputDir = new File("$buildDir/asciidoc/integrationguide/html_single")
+	outputDir = project.layout.buildDirectory.dir( 'asciidoc/integrationguide/html_single' )
 
 	attributes linkcss: true,
 				stylesheet: "css/hibernate.css"
@@ -218,6 +218,8 @@ task renderIntegrationGuide(type: AsciidoctorTask, group: 'Documentation') {task
 
 task renderMigrationGuide(type: AsciidoctorTask, group: 'Documentation') {task->
 	description = 'Renders the Migration Guide in HTML format using Asciidoctor.'
+
+	tasks.buildDocs.dependsOn task
 	tasks.buildDocsForPublishing.dependsOn task
 
 	sourceDir = rootProject.layout.projectDirectory
@@ -240,7 +242,50 @@ task renderMigrationGuide(type: AsciidoctorTask, group: 'Documentation') {task->
 	}
 }
 
-tasks.buildDocsForPublishing.dependsOn generateHibernateReports
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// ORM Reports
+
+task renderOrmReports { task ->
+	group 'Documentation'
+	description 'Grouping task for rendering all ORM reports'
+
+	dependsOn tasks.generateIncubationReport
+	dependsOn tasks.generateInternalsReport
+
+	tasks.buildDocs.dependsOn task
+	tasks.buildDocsForPublishing.dependsOn task
+}
+
+task renderLoggingReport(type: AsciidoctorTask, group: 'Documentation') { task ->
+	group 'Documentation'
+	description = 'Renders the ORM logging report in HTML format using Asciidoctor.'
+
+	dependsOn tasks.generateLoggingReport
+
+	tasks.renderOrmReports.dependsOn task
+
+	sourceDir = layout.buildDirectory.dir( 'orm/reports' )
+	sources {
+		include 'logging.adoc'
+	}
+
+	outputDir = project.layout.buildDirectory.dir( 'asciidoc/logging' )
+
+	attributes linkcss: true,
+			stylesheet: "css/hibernate.css"
+
+	resources {
+		from('src/main/style/asciidoctor') {
+			include 'images/**'
+		}
+		from('src/main/style/asciidoctor') {
+			include 'css/**'
+		}
+	}
+}
+
+
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 tasks.withType(AsciidoctorTask).all {
 	baseDirFollowsSourceDir()
@@ -250,31 +295,11 @@ tasks.withType(AsciidoctorTask).all {
 	}
 }
 
-// Testing
-
-test {
-	include '**/**'
-}
-
 // resources inherently exclude sources
 sourceSets.test.resources {
 	setSrcDirs( ['src/test/java','src/test/resources'] )
 }
 
 
-// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-// grouping tasks
-// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-buildDocs.dependsOn renderTopicalGuides
-buildDocs.dependsOn renderGettingStartedGuides
-buildDocs.dependsOn renderUserGuide
-buildDocs.dependsOn renderIntegrationGuide
-
-buildDocsForPublishing.dependsOn renderTopicalGuides
-buildDocsForPublishing.dependsOn renderGettingStartedGuides
-buildDocsForPublishing.dependsOn renderUserGuide
-buildDocsForPublishing.dependsOn renderIntegrationGuide
-
 checkstyleMain.exclude '**/org/hibernate/userguide/model/*'
 

hibernate-core/src/main/java/org/hibernate/internal/log/IncubationLogger.java

@@ -20,7 +20,7 @@ import static org.jboss.logging.Logger.Level.WARN;
 @MessageLogger(projectCode = "HHH")
 @ValidIdRange(min = 90006001, max = 90007000)
 public interface IncubationLogger {
-	String CATEGORY = SubSystemLogging.BASE + ".deprecation";
+	String CATEGORY = SubSystemLogging.BASE + ".incubating";
 
 	IncubationLogger INCUBATION_LOGGER = Logger.getMessageLogger( IncubationLogger.class, CATEGORY );
 

hibernate-orm-build/src/main/java/org/hibernate/orm/post/IncubationReportTask.java

@@ -25,7 +25,7 @@ public abstract class IncubationReportTask extends AbstractJandexAwareTask {
 	public IncubationReportTask(IndexManager indexManager, Project project) {
 		super(
 				indexManager,
-				project.getLayout().getBuildDirectory().file( "reports/orm/incubating.txt" )
+				project.getLayout().getBuildDirectory().file( "orm/reports/incubating.txt" )
 		);
 		setDescription( "Generates a report for things considered incubating" );
 	}

hibernate-orm-build/src/main/java/org/hibernate/orm/post/InternalsReportTask.java

@@ -27,7 +27,7 @@ public abstract class InternalsReportTask extends AbstractJandexAwareTask {
 	public InternalsReportTask(IndexManager indexManager, Project project) {
 		super(
 				indexManager,
-				project.getLayout().getBuildDirectory().file( "reports/orm/internal.txt" )
+				project.getLayout().getBuildDirectory().file( "orm/reports/internal.txt" )
 		);
 	}
 

hibernate-orm-build/src/main/java/org/hibernate/orm/post/LoggingReportTask.java

@@ -34,7 +34,7 @@ public abstract class LoggingReportTask extends AbstractJandexAwareTask {
 	public LoggingReportTask(IndexManager indexManager, Project project) {
 		super(
 				indexManager,
-				project.getLayout().getBuildDirectory().file( "reports/orm/logging.adoc" )
+				project.getLayout().getBuildDirectory().file( "orm/reports/logging.adoc" )
 		);
 	}
 

hibernate-orm-build/src/main/java/org/hibernate/orm/post/LoggingReportTask2.java

@@ -48,7 +48,7 @@ public abstract class LoggingReportTask2 extends AbstractJandexAwareTask {
 	public LoggingReportTask2(IndexManager indexManager, Project project) {
 		super(
 				indexManager,
-				project.getLayout().getBuildDirectory().file( "reports/orm/logging.adoc" )
+				project.getLayout().getBuildDirectory().file( "orm/reports/logging.adoc" )
 		);
 	}
 

release/release.gradle

@@ -215,11 +215,10 @@ task aggregateJavadocs(type: Javadoc) {
     }
 }
 
-
 task stageIntegrationGuide(type: Copy) {
     group 'Release'
 
-    dependsOn ':documentation:buildDocsForPublishing'
+    dependsOn ':documentation:renderIntegrationGuide'
 
     from "${project( ':documentation' ).buildDir}/asciidoc/integrationguide"
     into "${buildDir}/documentation/integrationguide"
@@ -229,7 +228,7 @@ task stageIntegrationGuide(type: Copy) {
 task stageQuickstart(type: Copy) {
     group 'Release'
 
-    dependsOn ':documentation:buildDocsForPublishing'
+    dependsOn ':documentation:renderGettingStartedGuides'
 
     from "${project( ':documentation' ).buildDir}/asciidoc/quickstart"
     into "${buildDir}/documentation/quickstart"
@@ -239,7 +238,7 @@ task stageQuickstart(type: Copy) {
 task stageTopicalGuide(type: Copy) {
     group 'Release'
 
-    dependsOn ':documentation:buildDocsForPublishing'
+    dependsOn ':documentation:renderTopicalGuides'
 
     from "${project( ':documentation' ).buildDir}/asciidoc/topical"
     into "${buildDir}/documentation/topical"
@@ -249,7 +248,7 @@ task stageTopicalGuide(type: Copy) {
 task stageUserGuide(type: Copy) {
     group 'Release'
 
-    dependsOn ':documentation:buildDocsForPublishing'
+    dependsOn ':documentation:renderUserGuide'
 
     from "${project( ':documentation' ).buildDir}/asciidoc/userguide"
     into "${buildDir}/documentation/userguide"
@@ -259,12 +258,49 @@ task stageUserGuide(type: Copy) {
 task stageMigrationGuide(type: Copy) {
     group 'Release'
 
-    dependsOn ':documentation:buildDocsForPublishing'
+    dependsOn ':documentation:renderMigrationGuide'
 
     from "${project( ':documentation' ).buildDir}/asciidoc/migration-guide"
     into "${buildDir}/documentation/migration-guide"
 }
 
+task stageOrmReports {
+    group 'Release'
+
+    dependsOn ':documentation:generateHibernateReports'
+}
+
+task stageOrmIncubationReport(type: Copy) { task ->
+    group 'Release'
+
+    dependsOn ':documentation:generateIncubationReport'
+    tasks.stageOrmReports.dependsOn task
+
+    from project( ":documentation" ).tasks.generateIncubationReport.reportFileReferenceAccess
+    into "${buildDir}/documentation/incubating"
+}
+
+task stageOrmInternalsReport(type: Copy) { task ->
+    group 'Release'
+
+    dependsOn ':documentation:generateInternalsReport'
+    tasks.stageOrmReports.dependsOn task
+
+    from project( ":documentation" ).tasks.generateInternalsReport.reportFileReferenceAccess
+    into "${buildDir}/documentation/internals"
+}
+
+task stageOrmLoggingReport(type: Copy) { task ->
+    group 'Release'
+
+    dependsOn ':documentation:renderLoggingReport'
+    tasks.stageOrmReports.dependsOn task
+
+    from project( ":documentation" ).tasks.renderLoggingReport.outputDir
+    into "${buildDir}/documentation/logging"
+}
+
+
 /**
  * Assembles all documentation into the {buildDir}/documentation directory.
  *
@@ -281,6 +317,7 @@ task assembleDocumentation {
     dependsOn tasks.stageQuickstart
     dependsOn tasks.stageUserGuide
     dependsOn tasks.stageMigrationGuide
+    dependsOn tasks.stageOrmReports
 }
 
 //task assembleProjectTemplates(type:Copy, dependsOn: project( ":project-template" ).tasks.assembleDist) {