diff --git a/COMMITTERS.adoc b/COMMITTERS.adoc new file mode 100644 index 0000000000000..2b29a5c0112be --- /dev/null +++ b/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 <> 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.