CONTRIBUTING.md

Contributing to QuestDB Java Client

Thank you for your interest in contributing to the QuestDB Java client library.

Table of Contents

• Contributing to QuestDB Java Client
  • Table of Contents
  • License and Code of Conduct
  • Reporting Bugs and Requesting Features
  • Environment Setup
    • Requirements
    • Repository Structure
  • Building
  • Running Tests
  • Before You Submit
    • Code Style
    • Testing
    • Commit Messages
    • PR Checklist
  • Pull Request Review Process

License and Code of Conduct

This project is licensed under the Apache License 2.0. By contributing, you agree that your contributions will be licensed under the same license.

All participants are expected to follow our Code of Conduct.

Reporting Bugs and Requesting Features

• Bugs and feature requests: Open an issue on GitHub Issues.
• Questions and discussions: Join the QuestDB Slack or post on the Community Forum.
• Security vulnerabilities: Please follow the process described in SECURITY.md. Do not open a public issue.

Environment Setup

Requirements

• Java: JDK 11 or later
• Maven: 3.0 or later
• QuestDB: A running instance is required for integration tests. Start one with Docker:

  docker run -p 9000:9000 -p 9009:9009 questdb/questdb

Repository Structure

client-java/
  core/         # Main client library (org.questdb:client)
  examples/     # Example applications

Building

Build the project without running tests:

mvn clean package -DskipTests

Build with Javadoc generation:

mvn clean package -DskipTests -Pjavadoc

Running Tests

Tests require a running QuestDB instance. Start one with Docker (see above), then:

mvn test

To generate a code coverage report:

mvn test -Pjacoco

The coverage report will be available at core/target/site/jacoco/index.html.

Before You Submit

Code Style

• Follow existing code conventions in the project.
• Use Java 11 language features as the minimum baseline.
• Ensure new public API methods include Javadoc.

Testing

• Add or update tests for any new functionality or bug fixes.
• Verify all existing tests pass before submitting.

Commit Messages

Use Conventional Commits format:

type: short description

Optional longer description.

Common types: feat, fix, docs, test, refactor, build, ci, chore.

Examples:

feat: add support for decimal columns
fix: handle connection timeout in HTTP sender
docs: update README with TLS configuration

PR Checklist

Before opening a pull request, ensure:

• Code compiles without warnings
• All existing tests pass
• New tests are added for new functionality
• Commit messages follow the Conventional Commits format
• Public API changes include Javadoc

Pull Request Review Process

1. Open a pull request against the main branch.
2. Provide a clear description of the change and its motivation.
3. A maintainer will review your PR and may request changes.
4. Once approved, a maintainer will merge the PR.

If you are unsure about an approach, open an issue or start a discussion on Slack before writing code.