Centralize release instructions in MAINTAINERS.md

As discussed offline.

Author: yrodiere

CONTRIBUTING.md

@@ -108,3 +108,11 @@ It is important that this topic branch of your fork:
 
 # Notes
 <sup>(1)</sup> Gradle `eclipse` plugin is no longer supported, so the recommended way to import the project in your IDE is with the proper IDE tools/plugins. Don't try to run `./gradlew clean eclipse --refresh-dependencies` from the command line as you'll get an error because `eclipse` no longer exists
+
+## <a id="ci"></a> Continuous integration
+
+See [MAINTAINERS.md](MAINTAINERS.md#ci) for information about CI.
+
+## <a id="releasing"></a> Releasing
+
+See [MAINTAINERS.md](MAINTAINERS.md#ci) for information about releasing.

MAINTAINERS.md

@@ -8,7 +8,7 @@ i.e. anybody with direct push access to the git repository.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).
 
-## Continuous integration
+## <a id="ci"></a> Continuous integration
 
 Continuous integration is split across two platforms:
 
@@ -46,6 +46,12 @@ See [Releasing](#releasing) for more information.
 
 ## <a id="releasing"></a> Releasing
 
+### Where is the information
+
+If you're looking for information about how releases are implemented technically, see [release/README.adoc](release/README.adoc).
+
+If you're looking for information about how to release Hibernate ORM, read on.
+
 ### Automated releases
 
 On select maintenance branches (`6.2`, `6.4`, ...),
@@ -71,12 +77,14 @@ In any case, before the release:
 * Check that the [CI jobs](#continuous-integration) for the branch you want to release are green.
 * Check Jira [Releases](https://hibernate.atlassian.net/projects/HHH?selectedItem=com.atlassian.jira.jira-projects-plugin%3Arelease-page):
   * Check that the release you are about to publish exists in Jira.
-  * Check there are no outstanding issues assigned to that release.
+  * Remove the fix version for anything rejected, etc.
+  * Move unresolved issues to another version
   * Check there are no resolved/closed issues in the corresponding "work-in-progress version"
     (e.g. `6.6`, `6.6-next`, ... naming convention may vary);
     if there are, you might want to assign them to your release.
+* Pull all upstream changes and perform `./gradlew preVerifyRelease` locally.
 
-**If it is a new major or minor release**, before the release:
+**If it's the first `Alpha`/`Beta` of a new major or minor release**, before the release:
 
 * Reset the migration guide to include only information relevant to the new major or minor.
 
@@ -93,7 +101,7 @@ Once you trigger the CI job, it automatically pushes artifacts to the
 and the documentation to [docs.jboss.org](https://docs.jboss.org/hibernate/orm/).
 
 * Do *not* mark the Jira Release as "released" or close issues,
-  the release job does it for you.
+  the release job triggers Jira automation that does it for you.
 * Do *not* update the repository (in particular changelog.txt and README.md), 
   the release job does it for you.
 * Trigger the release on CI:
@@ -118,10 +126,15 @@ After the job succeeds:
       to enable/disable the automatic release of the staging repository update the [jreleaser.yml](jreleaser.yml) file,
       in particular change the `deploy.maven.nexus2.maven-central.releaseRepository` to `true`/`false`.
 
-* Update [hibernate.org](https://github.com/hibernate/hibernate.org) if necessary:
-  * If it is a new major or minor release, add a `_data/projects/orm/releases/series.yml` file
-    and a `orm/releases/<version>/index.adoc` file.
-  * Adjust the release file in `_data/projects/orm/releases`: use a meaningful summary and set `announcement_url` to the blog post, if any.
+* Update [hibernate.org](https://github.com/hibernate/hibernate.org) as necessary:
+  * If it is a new major or minor release (new "series"):
+    * Add a `_data/projects/orm/releases/<series>/series.yml` file,
+      a `orm/releases/<series>/index.adoc` file, and a `orm/documentation/<series>/index.adoc` file.
+      Generally these files 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`
+    * Adjust the release file in `_data/projects/orm/releases` that was created automatically by the release job:
+      use a meaningful summary, if relevant, and set `announcement_url` to the blog post, if any.
+    * None of the above is necessary for maintenance (micro) releases.
   * Depending on which series you want to have displayed,
     make sure to adjust the `status`/`displayed` attributes of the `series.yml` file of the old series.
   * Push to the production branch.
@@ -133,8 +146,13 @@ After the job succeeds:
 
 #### Announcing the release
 
+If it is an `Alpha`, `Beta`, `CR` or first `Final` (`x.y.0.Final`) release, announce it:
+
+* Blog about release on [in.relation.to](https://github.com/hibernate/in.relation.to).
+  Make sure to use the tags "Hibernate ORM" and "Releases" for the blog entry.
 * Send an email to `[email protected]` and CC `[email protected]`.
 * Tweet about the release via the `@Hibernate` account.
+* Announce it anywhere else you wish (BlueSky, etc).
 
 #### Updating depending projects
 

README.adoc

@@ -13,11 +13,7 @@ See https://hibernate.org/orm/[Hibernate.org] for more information.
 
 == Continuous Integration
 
-Hibernate uses both https://jenkins-ci.org[Jenkins] and https://github.com/features/actions[GitHub Actions]
-for its CI needs. See
-
-* https://ci.hibernate.org/view/ORM/[Jenkins Jobs]
-* https://github.com/hibernate/hibernate-orm/actions[GitHub Actions Jobs]
+See link:MAINTAINERS.md#ci[MAINTAINERS.md] for information about CI.
 
 == Building from sources
 

release/README.adoc

@@ -1,47 +1,20 @@
 = ORM Releases
 :toc:
 
-This module performs the tasks needed as part of creating a release for Hibernate ORM.
-Releases are triggered as a link:../ci/release/Jenkinsfile[Jenkins pipeline].
-
-Hibernate ORM also publishes SNAPSHOT releases using an automated link:../ci/snapshot-publish.Jenkinsfile[Jenkins pipeline],
-which is triggered on a merge to the main branch. This job requires no user interactions.
-
-== Preparation
-
-There are a few steps that need to be performed prior to starting the release job:
-
-. 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
-
-If this is a new series, some additional steps are required to prepare the website:
+== Where is the information
 
-. 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`
+If you're looking for information about how to release Hibernate ORM, see link:/MAINTAINERS.md[MAINTAINERS.md]
 
+If you're looking for information about how releases are implemented technically, read on.
 
-== Perform the Release
+== How it works
 
-Start the appropriate Jenkins https://ci.hibernate.org/view/Release/job/hibernate-orm-release[job].
+Releases are triggered as a link:../ci/release/Jenkinsfile[Jenkins pipeline].
+Hibernate ORM also publishes SNAPSHOT releases using an automated link:../ci/snapshot-publish.Jenkinsfile[Jenkins pipeline],
+which is triggered on a merge to the main branch. This job requires no user interactions.
 
-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,
+When a release job 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] and leveraging link:../jreleaser.yml[JReleaser configuration].
 
 NOTE: Snapshot releases are not relying on JReleaser but on built-in Gradle publish plugin. See the link:../ci/snapshot-publish.Jenkinsfile[Jenkinsfile].
@@ -76,17 +49,3 @@ See https://plugins.gradle.org/plugin/org.hibernate.orm
 
 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).
-