From 5f10fa319d4b58d37ce68e6aaa953796241c11a3 Mon Sep 17 00:00:00 2001 From: Helber Belmiro Date: Tue, 29 Aug 2023 16:06:03 -0300 Subject: [PATCH] Added CONTRIBUTING.md (#451) * Added CONTRIBUTING.md Signed-off-by: Helber Belmiro * Added pull_request_template.md Signed-off-by: Helber Belmiro --------- Signed-off-by: Helber Belmiro --- CONTRIBUTING.md | 71 ++++++++++++++++++++++++++++++++++++++++ README.md | 2 ++ pull_request_template.md | 27 +++++++++++++++ 3 files changed, 100 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 pull_request_template.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..b283ebfc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,71 @@ +# Contributing guide + +**Want to contribute? Great!** We try to make it easy, and all contributions, even the smaller ones, are more than welcome. This includes bug reports, fixes, documentation, examples... But first, read this page. + +## Reporting an issue + +This project uses GitHub issues to manage the issues. Open an issue directly in GitHub. + +If you believe you found a bug, and it's likely possible, please indicate a way to reproduce it, what you are seeing, and +what you would expect to see. Don't forget to indicate your Quarkus, Java, Maven/Gradle, and GraalVM versions. + +## Tests and documentation are not optional + +Don't forget to include tests in your pull requests. Also don't forget the documentation (reference documentation, javadoc...). + +### RESTEasy Reactive and RESTEasy Classic + +This extension supports RESTEasy Reactive and RESTEasy Classic. We have one profile for each implementation. By default, tests are run with RESTEasy Classic. + +#### Using the RESTEasy Reactive profile + +To run the tests using RESTEasy Reactive, use the `resteasy-reactive` [profile](https://github.com/quarkiverse/quarkus-openapi-generator/blob/32d9bd753724065d7217defb3085a734fea40bc8/integration-tests/pom.xml#L79), like the following: + +```shell +mvn verify -Presteasy-reactive +``` + +#### Using the RESTEasy Classic profile + +To run the tests using RESTEasy Classic, use the `resteasy-classic` [profile](https://github.com/quarkiverse/quarkus-openapi-generator/blob/32d9bd753724065d7217defb3085a734fea40bc8/integration-tests/pom.xml#L49), like the following: + +```shell +mvn verify -Presteasy-classic +``` + +#### Specific tests for each implementation + +Most of the tests are the same for both RESTEasy implementations, but a few of them require different code, like the `multipart-request` [integration test](https://github.com/quarkiverse/quarkus-openapi-generator/tree/main/integration-tests/multipart-request). For these cases, we have one test for each implementation, using the `org.junit.jupiter.api.Tag` annotation to specify the profile for each of them. + +### Code Style + +Maven automatically formats code and organizes imports when you run `mvn verify`. So, we recommend you do that before sending your PR. Otherwise, PR checks will fail. + +## Quarkus 3 and Quarkus 2 support + +This extension supports versions 3 and 2 of Quarkus and the code base is different for each Quarkus version. Therefore, we have the `main` branch supporting Quarkus 3, and the `quarkus2` branch supporting Quarkus 2. Preferably send your PRs to the `main` branch and [we will backport them to the `quarkus2` branch](#backporting-between-branches). + +## For the maintainers + +### Backporting between branches + +[We have a GitHub action for backporting PRs between different branches](.github/workflows/pr-backporting.yml). To use that, you must set a label named `backport-`. + +Let's say you want to backport a PR from the `main` branch to the `quarkus2` branch. You would have to add a label named `backport-quarkus2` to the original PR. When that PR is merged, the GitHub actions bot will send a copy of the PR to the `quarkus2` branch. + +See an example: + +* [Original PR](https://github.com/quarkiverse/quarkus-openapi-generator/pull/439) +* [Backport PR](https://github.com/quarkiverse/quarkus-openapi-generator/pull/445) + +#### Known limitation + +GitHub does not initiate checks for pull requests opened by the GitHub Actions bot. Therefore, [when we backport a PR to another branch the PR checks are not run automatically](https://github.com/quarkiverse/quarkus-openapi-generator/issues/450). + +### Backlog + +We have a [Kanban board](https://github.com/orgs/quarkiverse/projects/2), which is currently visible only by members of the [Quarkiverse organization](https://github.com/quarkiverse). + +### Staling issues and PRs + +We have a [GitHub action to automatically close issues and PRs](.github/workflows/stale_issues.yml) that didn't have interactions for a while. If you want to disable it for a specific issue or PR, you can add the `pinned` label and it will never stale. \ No newline at end of file diff --git a/README.md b/README.md index 4a13d762..1f69697e 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,8 @@ project: https://opencollective.com/openapi_generator/donate This extension is for REST code generation for client side only. If you're looking for code generation for the server side, please take a look at the [Quarkus Apicurio Extension](https://github.com/Apicurio/apicurio-codegen/tree/main/quarkus-extension). +**Want to contribute? Great!** We try to make it easy, and all contributions, even the smaller ones, are more than welcome. This includes bug reports, fixes, documentation, examples... But first, read [this page](CONTRIBUTING.md). + ## Getting Started Add the following dependency to your project's `pom.xml` file: diff --git a/pull_request_template.md b/pull_request_template.md new file mode 100644 index 00000000..034af135 --- /dev/null +++ b/pull_request_template.md @@ -0,0 +1,27 @@ +Many thanks for submitting your Pull Request :heart:! + +Please make sure that your PR meets the following requirements: + +- [ ] You have read the [contributors guide](CONTRIBUTING.md) +- [ ] Your code is properly formatted according to [our code style](CONTRIBUTING.md#code-style) +- [ ] Pull Request title contains the target branch if not targeting main: `[0.9.x] Subject` +- [ ] Pull Request contains link to the issue +- [ ] Pull Request contains link to any dependent or related Pull Request +- [ ] Pull Request contains description of the issue +- [ ] Pull Request does not include fixes for issues other than the main ticket + +
+ +How to backport a pull request to a different branch? + + +In order to automatically create a **backporting pull request** please add one or more labels having the following format `backport-`, where `` is the name of the branch where the pull request must be backported to (e.g., `backport-quarkus2` to backport the original PR to the `quarkus2` branch). + +> **NOTE**: **backporting** is an action aiming to move a change (usually a commit) from a branch (usually the main one) to another one, which is generally referring to a still maintained release branch. Keeping it simple: it is about to move a specific change or a set of them from one branch to another. + +Once the original pull request is successfully merged, the automated action will create one backporting pull request per each label (with the previous format) that has been added. + +If something goes wrong, the author will be notified and at this point a manual backporting is needed. + +> **NOTE**: this automated backporting is triggered whenever a pull request on `main` branch is labeled or closed, but both conditions must be satisfied to get the new PR created. +