quarkus/COMMITTERS.adoc

= Information for Quarkus Committers

This document contains useful information for Quarkus committers.

[NOTE]
====
It is a work in progress, so if you think information is missing/unclear/inadequate,
please reach out to us on the `quarkus-dev` mailing-list.
====

This document has a lot of information.
It is not a set of strict rules, it is here to guide you.
If you forget to do something, miss something, don't worry, it happens.

Do your best and that will already be a lot :).

== Merging Pull Requests

The first thing is that, while being a committer,
you can't really commit directly to the main repository:
you need at least one review by your peers.

Thus, the need for a pull request.

So you are more like a merger than a committer
and you might merge more PRs from others than your own work.

While not absolute, here is some advice:

* If you really want a review from a specific person, make it a named reviewer via GitHub's "Reviewers" feature
* If someone asked for a specific reviewer, better give some time to this person to review the PR.
  If not reviewed in a reasonable amount of time, better ping them again to have some information
  or ask the original author if we should go ahead.
* If in doubt (on a specific part or because you're not comfortable reviewing documentation or any other reason),
  ask for help.
* Except if it's a total no-brainer (typically a typo fix), let the PR bake a few hours so some other people can have a
  look if interested.
  If the PR is very large or is a new extension, better let it
  bake for a few days.
* A pull request may not contain _merge commits_ (it makes backporting a lot harder) or `fixup!` commits.
* We merge pull requests with _merge commits_ so please ask the author to properly squash the commits before merging (when it makes sense).
  The idea is to have proper semantic commits. Several commits are not a problem as long as they have a proper semantic.
  If the author is not familiar with Git or not available, you can also (carefully)
  https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork[do it for them]
  as long as you both agreed on it.
* Make sure the commit comments are meaningful.
* As a new committer, you can start by giving your approval and not merging and see how things evolve.
  This should give you some hints on important things to check in the future.
* Only merge pull requests that target `main`.
  **Dealing with older branches is a separate process.**
* If you are sure a PR should go in and is just waiting for CI,
  just use the `triage/waiting-for-ci` label.
  It is a good hint for other committers.
* If you think a pull request is an essential part of a given milestone (and can realistically be a part of it),
  you should affect this milestone to it so that we can be sure it stays on the radar.
  Otherwise, better not do it and let the Quarkus bot do it for you.
* If you think a pull request is worth mentioning in the release notes and/or
  the announcement blog post, add the `release/noteworthy-feature` label.
* If you think a pull request introduces some breaking changes,
  add the `release/breaking-change` label, see <<backward-compatibility,Backward Compatibility>> for more details.
* Do NOT affect a PR to an old branch, see the <<backporting-process,backporting process>> for more details.

Obviously, each situation is different so use your own judgement,
and if in doubt, just ask for advice, the other committers are here to help.

[[release-schedule]]
== Release Schedule

The release schedule is posted here: https://github.com/quarkusio/quarkus/wiki/Release-Planning .

There are a few things you can do to help us be on schedule:

* Anything that goes in a release should have been **merged** the day before the release.
  That means:
+
  ** Your PR needs to be created, obviously.
  ** It should have been reviewed by someone familiar with this area.
  ** You have to take this feedback into account.
  ** And once approved, the PR can be merged.
  ** Also, keep in mind that we have a 3 hours CI cycle and CI needs to be green before any inclusion.
+
In short, posting a large PR the day before the release won't work.

* In the case of a significant change, the release considered for inclusion shouldn't be
  the `.Final` but the `.CR1.`.
  Thus, your PR has to be merged the day before the release of `.CR1`.

* If, for some reason, a PR really needs to be part of a given release, better coordinate with
  the release manager and the potential reviewers so that everyone is aware something big is coming.
  Potential reviewers might also have their own agenda and work to be included in the release,
  thus not always having the cycles to review last minute.

== Dependency Upgrades

Quarkus depends on a lot of third party dependencies that we try to keep up to date.

We partially rely on Dependabot for https://github.com/quarkusio/quarkus/blob/main/.github/dependabot.yml[a curated list of dependencies].

Some dependencies are critical for Quarkus and quite complex.
Good examples would be Netty, Vert.x or Hibernate ORM.

It is good practice to update these core dependencies at the beginning of a given
release cycle to let them time to bake in the main branch before being released.
And, in any case, we should avoid upgrading these dependencies after the CR1 when we can.

[[backward-compatibility]]
== Backward Compatibility

Quarkus evolves very fast, and we decided we could break backward compatibility as long as:

* It is worth it.
* We try to support the previous behavior for a while - if it doesn't have a prohibitive cost,
  be it in terms of development time or added complexity.

Usually, it is a good idea to have the opinion of people involved in the development of this area.
And for widely used extensions or core changes, sending an email to the `quarkus-dev` mailing list
should be considered.

When deprecating things, make sure to keep the deprecations for 12 months,
except you have a very good reason not doing so (and in this case, let's discuss it on quarkus-dev).

Breaking changes should be marked with the `release/breaking-change` label and,
if they need to be included in the release notes and/or announcement blog post,
they should also be labelled with `release/noteworthy-feature`.

They must be documented in the migration guide of the appropriate version:
https://github.com/quarkusio/quarkus/wiki/Migration-Guides.

== Pull Request Title

The title should be in English, should not contain an issue number.
It should also not contain ellipsis.

If your commit message was too long and GitHub automatically cut
the title, it is helpful if you can take the time to move the cut
part where it belongs to have a full title.

Titles are included in the Release notes, so they are important.

A good title would look like: `Fix off by one issue in Quartz extension` or
`Introduce Hibernate Reactive extension`.

A bad title would look like: `fix(#444)`.

== Issues Fixed

When a PR fixes some issues, it's good practice to add it in the description (and not in the title!).

One issue per line with something like:

[source,asciidoc]
----
* Fix #444
* Fix #555
----

Given GitHub automatically extracts the commit information to fill in the PR fields,
just make your commit comment look like:

[source]
----
Fix off by one issue in Quartz extension

* Fix #444
* Fix #555
----

[TIP]
====
GitHub supports a variety of keywords here: `fix`, `fixes`, `fixed`,
`resolve`, `resolves`, `resolved`, `close`, `closes`, `closed`
all do the same thing.
====

[WARNING]
====
GitHub won't detect issues properly if you do something like
`Fix #444 #555`.
====

== Affecting Labels and Milestones

Affecting labels and milestones is very important in our process.
The Quarkus Bot does it in most cases.

In some cases, you might have to add some manually though:

* If you close an issue that has not been closed automatically, either affect a milestone if it has been fixed
  or one of the `triage/invalid`, `triage/out-of-date`, `triage/wontfix` labels if not.
* Some issues are created as `kind/bug` but are more support questions:
  in this case, remove the `kind/bug` label and add the `kind/question` label
  or even better redirect them to the Discussions section.

[[backporting-process]]
== Backporting Process

When we release a new version of Quarkus, we usually do a bugfix
release a couple of weeks after.

Every time we do a major release (e.g. `2.7.0.Final`), we create a release branch (e.g. `2.7`) to host
the commits for these bugfix releases.

All the pull requests are merged in the `main` branch, so they are applied to the new feature
release of Quarkus.
They won't be integrated in the previous version branch.

Some pull requests however may qualify for being backported to this
bugfix branch.

Good examples of that might be:

* bugfixes
* documentation fixes
* usability fixes

Obviously, the barrier is higher for large pull requests as
they might be more risky to backport.
But sometimes, we just have to backport them anyway.

If you think your pull request or the pull request you are reviewing, might be a good backport candidate,
please add the `triage/backport?` label.

The question mark is important:
it is not automatic and we carefully review each pull request before backporting.

Thus, if not entirely clear, don't hesitate to add a comment to the pull request
when adding the label.

And don't be surprised if we come to you with some questions about it
when we prepare the next bugfix release.

== Good First Issues

We need to find the right balance between fixing the issues right away
and trying to onboard new contributors.

It's not always easy to find one, but if you think an issue is appropriate,
affecting the `good first issue` label to it for some time might be a good thing.

Obviously, critical bugs are not good candidates :).

== I Did Something Wrong, What Should I Do?

Take a deep breath and don't worry, it happens.

Just ping `@quarkusio/committerhelp` on GitHub or `@committerhelp` on Zulip,
and we will find a solution.