release details

Author: sebersole

Diff for: release/README.adoc

@@ -1,22 +1,86 @@
-This project coordinates the tasks that need to be performed as part of creating a release for Hibernate.
+= ORM Releases
+:toc:
 
-== Artifacts
+This module performs the tasks needed as part of creating a release for Hibernate ORM.  Releases are triggered as a Jenkins job.
 
-Both snapshot and release artifacts are published to Sonatype https://oss.sonatype.org/[OSSRH].
+== Preparation
 
-The "official" detials about OSSRH + Gradle can be found at https://central.sonatype.org/publish/publish-gradle/.
-However, its content is way out of date as of the time of this writing.
-https://dev.to/kengotoda/deploying-to-ossrh-with-gradle-in-2020-1lhi presents a much better guide.  Regardless,
-This is all just for background; all of this information is "backed into" the build scripts.
+There are a few steps that need to be performed prior to starting the release job:
 
-After release, be sure to manage the staging repository created for it on https://oss.sonatype.org/[OSSRH].
+. Pull all upstream changes and perform `./gradlew preVerifyRelease`.
+. Verify issues in the Jira version
+.. Remove fix version for anything rejected, etc.
+.. Move unresolved issues to another version
+. Mark version released in Jira
+. Bulk close all issues in the Jira version
 
+=== New Series
 
-== Documentation
+If this is a new series, some additional steps are required to prepare the website:
 
-JBoss doc server...
+. Create the series descriptor
+.. create the directory `_data/projects/orm/releases/${family_name}`
+.. create the file `series.yml`
+.. add the appropriate content (_generally this can be copied from previous series_)
+. Create the series listing
+.. create the directory `orm/releases/${family_name}`
+.. create the file `index.adoc`
+.. add listing of all new features in the series
+. Create the documentation listing
+.. create the directory `orm/documentation/${family_name}`
+.. create the file `index.adoc`
+.. add links to all documentation (_generally this can be copied from previous series_)
+. If this new series is to support a new JPA release, also be sure to update `orm/releases/index.adoc`
 
 
-== SourceForge
+== Perform the Release
+
+Start the appropriate Jenkins https://ci.hibernate.org/view/Release/job/hibernate-orm-release[job].
+
+NOTE: When a release is started, the job coordinates with the unified Hibernate https://github.com/hibernate/hibernate-release-scripts[release scripts] in a number of stages and steps,
+calling tasks on this module's link:./release.gradle[Gradle script].
+
+At a high-level, this process:
+
+* builds and verifies the individual modules
+* produces artifacts and publishes them
+* tags the release
+* updates the website
+
+This process has a number of "outputs"...
+
+
+=== Release Artifacts (jar)
+
+Release artifacts are published to https://oss.sonatype.org/[Sonatype OSSRH] (aka, Maven Central).  For each module, we publish:
+
+* The "main" jar
+* The sources jar
+* The javadoc jar
+
+
+=== Gradle Plugin
+
+The Gradle plugin gets published to Gradle's https://plugins.gradle.org/[Plugin Portal].
+
+See https://plugins.gradle.org/plugin/org.hibernate.orm
+
+
+=== Documentation
+
+All documentation for the release is generated, assembled and then published to the https://docs.jboss.org/hibernate/orm/[documentation server].
+
+
+== Announce
+
+If the release is a maintenance release, there is nothing more to do.
+
+However, for Alpha, Beta, CR and first Final releases some announcements are in order:
+
+. Write a release announcement blog post.
+. Announce the release, with link to the blob post:
+.. on the hibernate-dev and hibernate-announce mailing lists
+.. on the https://discourse.hibernate.org/[forums]
+.. on Twitter
+.. anywhere else you wish (BlueSky, etc).
 
-Release bundles (as ZIP and TGZ) are uploaded to https://sourceforge.net/projects/hibernate/files/hibernate-orm/[SourceForge]