Add COMMITTERS.adoc

COMMITTERS.adoc

@@ -0,0 +1,251 @@
+= 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 by a specific person, make it a named reviewer via GitHub's "Reviewers" UI
+* If someone asked for a specific reviewer, better give some time for 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.
+* We do merge commits so please ask the author to properly squash the commits before merging.
+  The idea is to have proper semantic commits.
+  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 of important things to check in the future.
+* Only merge pull requests that target master.
+  **Dealing with old 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.
+* 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.
+* When merging a pull request, please affect the corresponding milestone to the pull request
+  and the resolved issues.
+  The current master branch is marked with ` - master` on GitHub.
+  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 be 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/master/.github/dependabot.yml[a curated list of dependencies].
+
+Some dependencies are critical for Quarkus and quite complex.
+Good examples would be 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 master branch before being released.
+
+== 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 on the `quarkus-dev` mailing list
+should be considered.
+
+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.
+
+Before each release, we check that we don't have any
+closed issues that don't have either a milestone affected or
+some of the "excluding" labels.
+
+Thus:
+
+* When you merge a pull request, please affect it with the current milestone marked with "master".
+* If the pull request has issues associated (i.e. if the pull request fixes some issues),
+  you should also affect the milestone assigned to the issues.
+* If you close a pull request because the committers have decided to not merge it,
+  please add the appropriate `triage/` label: `triage/invalid`, `triage/out-of-date`,
+  `triage/wontfix` are usually in order.
+* If you close an issue because it has been fixed, either add the milestone
+  if you can find it easily or use the `triage/out-of-date` if you can't.
+* If you close an issue for any other reason, one of the aforementioned `triage/` labels
+  is probably adequate.
+* 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.
+
+[[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. `1.7.0.Final`), we create a release branch (e.g. `1.7`) to host
+the commits for these bugfix releases.
+
+All the pull requests are merged in the `master` 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 issue right away
+and trying to onboard new contributors.
+
+It's not always easy to find one, but if you think the issue is appropriate,
+affecting it the `good first issue` label 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.