Add a deprecated.txt report to published docs collecting union of `@Deprecated` and `@Remove`

documentation/documentation.gradle

@@ -256,6 +256,7 @@ task renderOrmReports { task ->
 
 	dependsOn tasks.generateIncubationReport
 	dependsOn tasks.generateInternalsReport
+	dependsOn tasks.generateDeprecationReport
 
 	tasks.buildDocs.dependsOn task
 	tasks.buildDocsForPublishing.dependsOn task

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

@@ -13,6 +13,7 @@ import java.io.IOException;
 import java.io.OutputStreamWriter;
 import java.util.List;
 import java.util.TreeSet;
+import java.util.function.Consumer;
 import javax.inject.Inject;
 
 import org.gradle.api.DefaultTask;
@@ -89,17 +90,25 @@ public class AbstractJandexAwareTask extends DefaultTask {
 	}
 
 	protected void processAnnotations(DotName annotationName, TreeSet<Inclusion> inclusions) {
+		processAnnotations( inclusions::add, annotationName );
+	}
+
+	protected void processAnnotations(Consumer<Inclusion> inclusions, DotName... annotationNames) {
 		final Index index = getIndexManager().getIndex();
+
+		for ( int i = 0; i < annotationNames.length; i++ ) {
+			final DotName annotationName = annotationNames[ i ];
 			final List<AnnotationInstance> usages = index.getAnnotations( annotationName );
 
 			usages.forEach( (usage) -> {
 				final AnnotationTarget usageLocation = usage.target();
 				final Inclusion inclusion = determinePath( usageLocation );
 				if ( inclusion != null ) {
-				inclusions.add( inclusion );
+					inclusions.accept( inclusion );
 				}
 			} );
 		}
+	}
 
 	protected void writeReport(TreeSet<Inclusion> inclusions) {
 		final File reportFile = prepareReportFile();
@@ -116,7 +125,13 @@ public class AbstractJandexAwareTask extends DefaultTask {
 		}
 	}
 
+	protected void writeReportHeader(OutputStreamWriter fileWriter) {
+		// by default, nothing to do
+	}
+
 	private void writeReport(TreeSet<Inclusion> inclusions, OutputStreamWriter fileWriter) {
+		writeReportHeader( fileWriter );
+
 		String previousPath = null;
 		for ( Inclusion inclusion : inclusions ) {
 			if ( previousPath != null && inclusion.getPath().startsWith( previousPath ) ) {

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

@@ -0,0 +1,65 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
+ * See the lgpl.txt file in the root directory or http://www.gnu.org/licenses/lgpl-2.1.html.
+ */
+package org.hibernate.orm.post;
+
+import java.io.IOException;
+import java.io.OutputStreamWriter;
+import java.util.Comparator;
+import java.util.TreeSet;
+import javax.inject.Inject;
+
+import org.gradle.api.Project;
+import org.gradle.api.tasks.TaskAction;
+
+import org.jboss.jandex.DotName;
+
+/**
+ * @author Steve Ebersole
+ */
+public class DeprecationReportTask extends AbstractJandexAwareTask {
+	public static final String REMOVE_ANN_NAME = "org.hibernate.Remove";
+	public static final String DEPRECATED_ANN_NAME = Deprecated.class.getName();
+
+	@Inject
+	public DeprecationReportTask(IndexManager indexManager, Project project) {
+		super(
+				indexManager,
+				project.getLayout().getBuildDirectory().file( "orm/reports/deprecating.txt" )
+		);
+		setDescription( "Generates a report for things considered deprecating" );
+	}
+
+	@TaskAction
+	public void generateIncubationReport() {
+		final TreeSet<Inclusion> deprecations = new TreeSet<>( Comparator.comparing( Inclusion::getPath ) );
+
+		processAnnotations(
+				deprecations::add,
+				DotName.createSimple( REMOVE_ANN_NAME ),
+				DotName.createSimple( DEPRECATED_ANN_NAME )
+		);
+
+		// NOTE : at this point, `deprecations` contains a set of deprecation
+		// names ordered alphabetically..
+
+		writeReport( deprecations );
+	}
+
+	@Override
+	protected void writeReportHeader(OutputStreamWriter fileWriter) {
+		super.writeReportHeader( fileWriter );
+
+		try {
+			fileWriter.write( "# Union of everything annotated @Deprecated and/or @Remove" );
+			fileWriter.write( '\n' );
+			fileWriter.write( '\n' );
+		}
+		catch (IOException e) {
+			throw new RuntimeException( e );
+		}
+	}
+}

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

@@ -43,6 +43,14 @@ public class ReportGenerationPlugin implements Plugin<Project> {
 		incubatingTask.dependsOn( indexerTask );
 		groupingTask.dependsOn( incubatingTask );
 
+		final DeprecationReportTask deprecationTask = project.getTasks().create(
+				"generateDeprecationReport",
+				DeprecationReportTask.class,
+				indexManager
+		);
+		deprecationTask.dependsOn( indexerTask );
+		groupingTask.dependsOn( deprecationTask );
+
 		final InternalsReportTask internalsTask = project.getTasks().create(
 				"generateInternalsReport",
 				InternalsReportTask.class,

release/release.gradle

@@ -283,6 +283,16 @@ task stageOrmInternalsReport(type: Copy) { task ->
     into "${buildDir}/documentation/internals"
 }
 
+task stageOrmDeprecationReport(type: Copy) { task ->
+    group 'Release'
+
+    dependsOn ':documentation:generateDeprecationReport'
+    tasks.stageOrmReports.dependsOn task
+
+    from project( ":documentation" ).tasks.generateDeprecationReport.reportFileReferenceAccess
+    into "${buildDir}/documentation/deprecated"
+}
+
 task stageOrmLoggingReport(type: Copy) { task ->
     group 'Release'