[repo] Contribution guide#2859
Open
chernser wants to merge 2 commits into
Open
Conversation
|
Repository collaborators can run the JMH benchmark suite against this PR by commenting: Optional regression threshold override (Δ% on Time or Alloc/op; defaults to 10%): Only one benchmark run per PR is active at a time — issuing a new |
joe-clickhouse
approved these changes
May 21, 2026
mshustov
reviewed
May 26, 2026
|
|
||
| Contributions are always welcome: issues, pull requests, questions, ideas, tests, documentation, and examples all help the project. | ||
|
|
||
| ClickHouse Java is maintained by a team responsible for the stability and quality of released artifacts. Because this repository publishes client libraries and drivers used by applications, every contribution needs enough context and validation for maintainers to review its safety. At minimum, a code change should include a clear description and tests that prove the intended behavior. |
Member
There was a problem hiding this comment.
every contribution needs enough context and validation for maintainers to review its safety
I'd suggest rephrase to something > here's what makes them easy to review, otherwise, it reads too defensively
|
|
||
| Contributions are always welcome: issues, pull requests, questions, ideas, tests, documentation, and examples all help the project. | ||
|
|
||
| ClickHouse Java is maintained by a team responsible for the stability and quality of released artifacts. Because this repository publishes client libraries and drivers used by applications, every contribution needs enough context and validation for maintainers to review its safety. At minimum, a code change should include a clear description and tests that prove the intended behavior. |
Member
There was a problem hiding this comment.
Because this repository publishes client libraries and drivers used by applications, every contribution needs enough context and validation for maintainers to review its safety.
I'd even strengthen it
The libraries are foundational infrastructure for the software built on top of them, thus a regression or breaking change in a client propagates to applications that depends on it, often with limited ability for users to work around the issue
There was a problem hiding this comment.
Maybe
ClilckHouse client libraries are deployed in production environments all over the world. Our users and customers depend on them being thoughtfully designed, well documented, and highly reliable. The high bar for quality we apply to all our software must apply to external contributions as well.
Contributor
Author
There was a problem hiding this comment.
What about:
Libraries in this repository are used in many production systems. Users expect certain level of quality and
active support (adding new features, fixing issues). It is important to make all changes safe and swiftly.
There we ask all contributors for tests and clear description of changes done in a PR. This expedites merge and quadruples value of your contribution.
|
|
||
| ### Big Contributions | ||
|
|
||
| Large changes are easier to review and merge when they are split into a few smaller pull requests. From our experience, it is often better to prepare the codebase first with focused cleanup, refactoring, or test-only PRs, and then add the feature or behavior change in a later PR. |
Member
There was a problem hiding this comment.
The principle is right but the guidance doesn't have an easy to follow definition. Let's give contributors a concrete threshold. For example (numbers are taken from this study https://www.propelcode.ai/blog/pr-size-impact-code-review-quality-data-study):
As a rough guideline, if a pull request is over 300–400 lines of code (excluding docs and tests), consider whether it can be split. Smaller PRs are reviewed and merged faster, and the savings in review time usually outweigh the overhead of splitting
Contributor
Author
There was a problem hiding this comment.
We all know that large PRs (400+ lines of code) are hard to review and it is more likely to miss a bug. Small changes are appreciated and take less time to verify them. If many changes are needed anyway (feature implementation, refactoring), please split them: something can be done as code preparation, cleanup or smaller improvement. It should take less time at sum as this repository is actively maintained. We will ask to split changes of 800+ LOC anyway.
| @@ -1,125 +1,194 @@ | |||
| ## Getting started | |||
| ClickHouse-JDBC client is an open-source project, and we welcome any contributions from the community. Please share your ideas, contribute to the codebase, and help us maintain up-to-date documentation. | |||
| # Contributing to ClickHouse Java | |||
Member
There was a problem hiding this comment.
Most of the guidance provided in the document (Testing, Contribution Process, significant contributions, and the PR checklist) is also relevant to AI coding agents. Considering the significant portion of our contributions made by agents, we should either mirror these rules into AGENTS.md or extract them into a shared file that both documents reference.
This can be done in a separate PR.
There was a problem hiding this comment.
Can the AGENTS.md just say "please also read CONTRIBUTING.md"?
Contributor
Author
There was a problem hiding this comment.
@mshustov
I agree. Will write something.
@abonander
This might be a good idea.
mshustov
reviewed
May 26, 2026
|
I really like where this is going. The only thing I'm weary of is that the longer it gets, the less likely a human is going to read the entire thing. An agent will no problem, so the length with detailed justifications and directions is great, but it might be worth having a short bulleted TLDR section at the top that provides md links to the relevant sections? e.g: ⚡ TLDR
- Proposals: Small fix? Just open a PR. Big feature or API change? Open an [Issue](#issues-discussion-and-proposals) first.
- PR Requirements: Every PR needs a clear description, tests, and a CHANGELOG.md update. See the full [PR Checklist](#pull-request-checklist).
- Testing: Code changes require both positive and negative tests. Keep them focused. More in [Testing Expectations](#testing-expectations).
- Quick Build Command (JDK 17+): `mvn -DskipITs` clean verify (Requires [Toolchains setup](#set-up-the-environment)).
- Run Local Tests: Unit tests run automatically. For Integration Tests, ensure Docker is running. Learn how to [Run Unit and Integration Tests](#run-unit-and-integration-tests). |
Contributor
Author
|
thank you for the feedback! Document is mainly focused for people not agents. I will add suggested section at header and will try to minimize wording to make document shorter and may be bit more structured. |
|
Client V2 CoverageCoverage Report
Class Coverage
|
JDBC V2 CoverageCoverage Report
Class Coverage
|
JDBC V1 CoverageCoverage Report
Class Coverage
|
Client V1 CoverageCoverage Report
Class Coverage
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Reworked contribution guide to tell more about process and expectations.
We should value every ones time and reduce review cycles so we explain how to prepare PR for best result.
Note
Low Risk
Documentation-heavy changes plus a profile/workflow rename; CI behavior should be equivalent if
-Pcoveragematches the old-PanalysisJaCoCo setup.Overview
Reworks
CONTRIBUTING.mdinto a fuller contribution guide: process (when to open issues/proposals, PR size and scope), testing expectations (including negative tests and coverage quality), a PR checklist (CHANGELOG.md,docs/features.md, local CI), restricted CI workflow changes, and a structured Technical Verification section (build, unit/integration tests, optional native binary and benchmarks).Aligns coverage tooling naming: the root Maven profile
analysisis renamed tocoverage, and the GitHub workflow is retitled from Analysis to Coverage with the Sonar step using-Pcoverageinstead of-Panalysis(same JaCoCo/Sonar flow, clearer name for contributors).Reviewed by Cursor Bugbot for commit 85907ef. Bugbot is set up for automated code reviews on this repo. Configure here.