This is an automated email from the ASF dual-hosted git repository.
snazy pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/polaris.git
The following commit(s) were added to refs/heads/main by this push:
new f16f50b88 Site/contributing: add recommendations for working with PRs
(#1625)
f16f50b88 is described below
commit f16f50b887e881789fd04e07f5d8de866bc29879
Author: Robert Stupp <[email protected]>
AuthorDate: Wed May 28 20:22:15 2025 +0200
Site/contributing: add recommendations for working with PRs (#1625)
This change updates the PR guidelines on the "Contributing" web page after
[this
discussion](https://lists.apache.org/thread/kfxo3cqmw3pgrpgtgqvqpwvn46yw8q7h).
Also adopt `gradlew test` to `gradlew check` in README, following the
intent (all tests, incl ITs)
---
CONTRIBUTING.md | 74 +++++++++++++++++++++++++++++++++++++++------------------
README.md | 2 +-
2 files changed, 52 insertions(+), 24 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d01dca6d2..f843b42b6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -64,32 +64,60 @@ Before starting on a large code change, please describe the
concept/design of wh
The best way to provide changes is to fork Apache Polaris repository on GitHub
and provide a Pull Request with your changes. To make it easy to apply your
changes please use the following conventions:
-* Every Pull Request should have a matching GitHub Issue.
-* Create a branch that will house your change:
-
-```bash
-git clone https://github.com/apache/polaris
-cd polaris
-git fetch --all
-git checkout -b my-branch origin/main
-```
-
- Don't forget to periodically rebase your branch:
-
-```bash
-git pull --rebase
-git push GitHubUser my-branch --force
-```
-
- Ensure the code is properly formatted:
-
-```bash
-./gradlew format
-```
+#### Before opening a pull request
* Pull Requests should be based on the `main` branch.
-* Test that your changes works by adapting or adding tests. Verify the build
passes (see `README.md` for build instructions).
+* Create a branch that will house your change:
+ ```bash
+ git clone https://github.com/apache/polaris
+ cd polaris
+ git checkout main
+ git pull
+ git checkout -b my-branch
+ ```
+* Work on the changes of your pull requests locally.
+* Recommended checks:
+ ```bash
+ # Ensure the code is properly formatted and compiles:
+ ./gradlew format compileAll
+ # Ensure the code is passing the checks (including formatting checks &
tests):
+ ./gradlew check
+ ```
+* You may want to push your changes to your personal Polaris fork. Git will
emit a URL that you can use to create the Pull Request. Do not create the Pull
Request yet.
+ ```bash
+ git push --set-upstream your-github-accout
+ ```
+
+#### Opening a Pull Request
+
+* The Pull Request summary should provide a concise summary of the change, get
inspired by [Conventional
Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+* The Pull Request description should provide the background (rationale) of
the change and describe the changes in way that someone who has no prior
knowledge can understand the rationale of the change and the change itself.
+* If there is a matching GitHub Issue, add a separate line at the end of the
commit message of the issue that the PR fixes. Do not add the issue number into
the subject.
+ ```
+ Fixes #123456
+ ```
+ If the PR does not fully fix the issue, use `Related to #123456` instead of
`Fixes #123456`.
+
+Tips:
+* If the branch for your Pull Request contains only one (squashed) commit,
GitHub will populate the PR summary and description from that single commit.
+* When opening a PR consider whether the PR is "draft" or already "ready for
review". "Draft" means work in progress, things will change, but comments are
welcome. "Ready for review" means that the PR is requested to be merged as is
(pending review feedback).
+
+#### Working on a Pull Request
+
+* Don't forget to periodically rebase your branch:
+ ```bash
+ git pull --rebase
+ git push your-github-accout my-branch --force
+ ```
+* Test that your changes work by adapting or adding tests. Verify the build
passes (see `README.md` for build instructions).
* If your Pull Request has conflicts with the `main` branch, please rebase and
fix the conflicts.
+* If your PR requires more work or time or bigger changes, please put the PR
to "draft" state to indicate that it is not meant to be "thoroughly" reviewed
at this point.
+
+#### Merging a Pull Request
+
+* When a PR is about to be merged, cross-check the commit summary and message
for the merged Git commit.
+* Keep in mind that the Git commit subject and message is going to be read by
other people, potentially even after years. The Git commit subject and message
will appear "as is" in release notes.
+* Make sure the subject and message are properly formatted and contains a
concise description of the changes in way that someone who has no prior
knowledge can understand the rationale of the change and the change itself.
Remove information that's of no use for someone reading the Git commit log, for
example single intermediate commit messages like `formatting` or `fix test`.
## Java version requirements
diff --git a/README.md b/README.md
index bf887d4aa..58891eb12 100644
--- a/README.md
+++ b/README.md
@@ -67,7 +67,7 @@ Apache Polaris is built using Gradle with Java 21+ and Docker
27+.
- `./gradlew build` - To build and run tests. Make sure Docker is running, as
the integration tests depend on it.
- `./gradlew assemble` - To skip tests.
-- `./gradlew test` - To run unit tests and integration tests.
+- `./gradlew check` - To run all checks, including unit tests and integration
tests.
- `./gradlew run` - To run the Polaris server locally; the server is reachable
at localhost:8181. This is also suitable for running regression tests, or for
connecting with Spark. Set your own credentials by specifying system property
`./gradlew run -Dpolaris.bootstrap.credentials=POLARIS,root,secret` where:
- `POLARIS` is the realm
- `root` is the CLIENT_ID
