Skip to content

Commit 9c0d988

Browse files
yrodierebeikov
yrodiere
authored and
beikov
committed
Add MAINTAINERS.md to describe how to release.
1 parent 978860f commit 9c0d988

File tree

2 files changed

+147
-1
lines changed

2 files changed

+147
-1
lines changed

‎MAINTAINERS.md

+146
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
Guide for maintainers of Hibernate ORM
2+
====
3+
4+
This guide is intended for maintainers of Hibernate ORM,
5+
i.e. anybody with direct push access to the git repository.
6+
7+
## Contributing
8+
9+
See [CONTRIBUTING.md](CONTRIBUTING.md).
10+
11+
## Continuous integration
12+
13+
Continuous integration is split across two platforms:
14+
15+
* GitHub Actions at https://github.com/hibernate/hibernate-orm/actions
16+
* a self-hosted Jenkins instance at https://ci.hibernate.org.
17+
18+
### GitHub Actions workflows
19+
20+
TODO: describe the workflows available.
21+
22+
### Jenkins main pipeline
23+
24+
https://ci.hibernate.org/job/hibernate-orm-pipeline/
25+
26+
This job takes care of testing additional DBs for:
27+
28+
* Primary branch builds
29+
* Pull request builds
30+
31+
It is generally triggered on push,
32+
but can also be triggered manually,
33+
which is particularly useful to test more environments on a pull request.
34+
35+
See [Jenkinsfile](Jenkinsfile) for the job definition.
36+
37+
### Release pipeline
38+
39+
https://ci.hibernate.org/job/hibernate-orm-release/
40+
41+
This job takes care of releases. It is triggered manually.
42+
43+
See [ci/release/Jenkinsfile](ci/release/Jenkinsfile) for the job definition.
44+
45+
See [Releasing](#releasing) for more information.
46+
47+
## <a id="releasing"></a> Releasing
48+
49+
### Automated releases
50+
51+
On select maintenance branches (`6.2`, `6.4`, ...),
52+
micro releases (`x.y.1`, `x.y.2`, ...) are performed as soon as you push to that branch.
53+
54+
Make sure to assign fix versions properly before merging pull requests.
55+
56+
No announcements are expected for such releases:
57+
neither through X, blog posts, or email.
58+
59+
### Manual releases
60+
61+
On `main` and some maintenance branches (`6.5`, ...),
62+
automated releases are disabled.
63+
64+
You must perform releases by manually triggering a CI job.
65+
66+
#### Preparing the release
67+
68+
In any case, before the release:
69+
70+
* Check that everything has been pushed to the upstream repository.
71+
* Check that the [CI jobs](#continuous-integration) for the branch you want to release are green.
72+
* Check Jira [Releases](https://hibernate.atlassian.net/projects/HHH?selectedItem=com.atlassian.jira.jira-projects-plugin%3Arelease-page):
73+
* Check that the release you are about to publish exists in Jira.
74+
* Check there are no outstanding issues assigned to that release.
75+
* Check there are no resolved/closed issues in the corresponding "work-in-progress version"
76+
(e.g. `6.6`, `6.6-next`, ... naming convention may vary);
77+
if there are, you might want to assign them to your release.
78+
79+
**If it is a new major or minor release**, before the release:
80+
81+
* Reset the migration guide to include only information relevant to the new major or minor.
82+
83+
**If it's a `.CR` or `.Final` release**, before the release:
84+
85+
* Check that the [migration guide](documentation/src/main/asciidoc/migration/index.adoc) is up to date.
86+
In particular, check the git history for API/SPI changes
87+
and document them in the migration guide.
88+
89+
#### Performing the release
90+
91+
Once you trigger the CI job, it automatically pushes artifacts to the
92+
[OSSRH repository manager](https://oss.sonatype.org/#stagingRepositories),
93+
the distribution to [SourceForge](https://sourceforge.net/projects/hibernate/files/hibernate-search/)
94+
and the documentation to [docs.jboss.org](https://docs.jboss.org/hibernate/search/).
95+
96+
* Do *not* mark the Jira Release as "released" or close issues,
97+
the release job does it for you.
98+
* Do *not* update the repository (in particular changelog.txt and README.md),
99+
the release job does it for you.
100+
* Trigger the release on CI:
101+
* Go to CI, to [the "hibernate-orm-release" CI job](https://ci.hibernate.org/job/hibernate-orm-release/).
102+
* Click the "run" button (the green triangle on top of a clock, to the right) next to the branch you want to release.
103+
* **Be careful** when filling the form with the build parameters.
104+
Note only `RELEASE_VERSION` is absolutely necessary.
105+
* Note that for new branches where the job has never run, the first run may not ask for parameters and thus may fail:
106+
that's expected, just run it again.
107+
* After the job succeeds, check the artifacts are available on Maven Central:
108+
https://repo1.maven.org/maven2/org/hibernate/hibernate-core/.
109+
They should appear after a few minutes, sometimes a few hours.
110+
111+
#### Announcing the release
112+
113+
* Blog about release on [in.relation.to](https://github.com/hibernate/in.relation.to).
114+
Make sure to use the tags "Hibernate ORM" and "Releases" for the blog entry.
115+
Use [release-announcement.adoc](release-announcement.adoc) as a starting point.
116+
* Update [hibernate.org](https://github.com/hibernate/hibernate.org) if necessary:
117+
* If it is a new major or minor release, add a `_data/projects/orm/releases/series.yml` file
118+
and a `orm/releases/<version>/index.adoc` file.
119+
* Adjust the release file in `_data/projects/orm/releases`: use a meaningful summary and set `announcement_url` to the blog post, if any.
120+
* Depending on which series you want to have displayed,
121+
make sure to adjust the `status`/`displayed` attributes of the `series.yml` file of the old series.
122+
* Push to the production branch.
123+
* Send an email to `[email protected]` and CC `[email protected]`.
124+
* Tweet about the release via the `@Hibernate` account.
125+
126+
#### Updating depending projects
127+
128+
If you just released the latest stable, you will need to update other projects:
129+
130+
* Approve and merge automatic updates that dependabot will send (it might take ~24h):
131+
* In the [test case templates](https://github.com/hibernate/hibernate-test-case-templates/tree/master/search).
132+
* In the [demos](https://github.com/hibernate/hibernate-demos/tree/master/hibernate-search).
133+
* **If it's a `.Final` release**, upgrade the Hibernate ORM dependency manually:
134+
* In the [Quarkus BOM](https://github.com/quarkusio/quarkus/blob/main/bom/application/pom.xml).
135+
* In any other relevant project.
136+
137+
#### Updating Hibernate ORM
138+
139+
In any case:
140+
141+
* Reset [release-announcement.adoc](release-announcement.adoc).
142+
143+
**If it is a new major or minor release**:
144+
145+
* Reset the migration guide on the `main` branch if you forgot about it when preparing the release.
146+
* Create a maintenance branch for the previous series, if necessary; see [branching](branching.adoc).

‎branching.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Describes the paradigm used for branching within the ORM project
1111
* PR branches for performance improvements, security fixes and bugfixes target the affected minor branches (which could be main for a short period of time)
1212

1313
[[process]]
14-
== THe Process
14+
== The Process
1515

1616
Process (using 6.3 -> 6.4 as an example):
1717

0 commit comments

Comments
 (0)