Skip to content

Latest commit

 

History

History
132 lines (88 loc) · 6.08 KB

CONTRIBUTING.md

File metadata and controls

132 lines (88 loc) · 6.08 KB

Contributing to Timefold Solver

First off, thanks for showing willingness to contribute to this repository by looking at this file. We are happy to have you here!

All types of contributions are encouraged and valued. In this file, we list different ways you can help the project and details about how this project handles them.

Q&A

"I have a question"

Before you ask a question, it is best to search through our extensive documentation and for existing issues.
It is also advisable to check the internet and/or ask your favorite LLM.

If you can't find a satisfying answer, post a message on our GitHub discussions or on our Discord server.

"I have (found) an issue"

First check if we already have a ticket for your problem by looking at our existing Issues.

  • In case you have found a suitable issue and still need clarification, you can write your question in this issue.
  • If the issue does not exist yet, please create a new one using the appropriate template (Bug report, feature request, ...).

"I have an idea to improve Timefold"

We'd love to hear your ideas! Talk to us about them here on GitHub or on our Discord server

"I want to help out!"

Excellent! We have issues labeled specifically for first time contributors. You can find them either on:

If you are starting out, we recommend working on the quickstarts first, as those usually require no knowledge of the internal architecture of the solver.

Note

The quickstart repository has a separate CONTRIBUTING file which is slightly different from the one you are reading now.

Development

Important

All contributions must comply with the Timefold Solver Constitution. The constitution defines our core principles, technology stack, code quality standards, and development practices. Key areas include:

  • Core Principles: Fail Fast, Understandable Error Messages, Consistent Terminology, Real World Usefulness, Automated Testing, Good Code Hygiene
  • Technology Stack: JDK 21 compatibility, nullability policy, dependency constraints, test infrastructure, security requirements
  • Code Quality: SonarCloud quality gates (Reliability ≥ B, Maintainability ≥ B), code coverage requirements, automated formatting
  • Package Structure: Public API (api packages) and Configuration (config packages) are 100% backwards compatible; Implementation can change freely

Please review the constitution before contributing to understand the project's standards and requirements.

From idea to Pull Request

Once you have selected an issue you want to work on:

  1. Fork Timefold Solver.
  2. Create a feature branch: git checkout -b feature
  3. Commit your changes with a comment: git commit -m "feat: add shiny new feature"
    (See Commit Messages for details.)
  4. Push to the branch to GitHub: git push origin feature
  5. Create a new Pull Request.

The CI checks against your PR to ensure that it doesn't introduce errors. If the CI identifies a potential problem, our friendly PR maintainers will help you resolve it.

Build the Timefold Solver Project

Use one of the following ways to build this project:

  • 🚀 build-fast: ./mvnw clean install -Dquickly - Skips checks and code analysis (~1 min)
  • 🔨 build-normally: ./mvnw clean install - Runs tests, checks code style, skips documentation (~17 min)
  • 📄 build-doc: ./mvnw clean install in the docs directory - Creates asciidoctor documentation docs/target/html_single/index.html (~2 min)
  • 🦾 build-all: ./mvnw clean install -Dfull - Runs all checks, creates documentation and distribution files (~20 min)

Code Style

Your code is automatically formatted according to the project conventions during every Maven build. CI checks enforce those conventions too, so be sure to build your project with Maven before creating your PR:

./mvnw clean install

For information about how to set up code style checks in your IDE, see IDE Setup Instructions.

Key code style conventions (see Constitution for complete details):

  • Automatic formatting via Maven build
  • Use newlines sparingly to separate logical blocks
  • When multiple class fields are touched, use/modify them in declaration order
  • Follow standard Java conventions

Commit Messages

We use Conventional Commits for PR titles and commit messages.

This convention is enforced by CI checks on pull requests.

Quality Gates

All PRs must pass the following automated checks:

SonarCloud Quality Gates

  • Reliability: Grade must be B or better (strive for A)
  • Maintainability: Grade must be B or better (strive for A)
  • Code Coverage: Must not fall below the configured threshold

PRs that worsen grades below B will fail CI and cannot be merged.

Security Scanning

  • Aikido: Performs automated security checks
  • Dependabot: Provides weekly dependency upgrade PRs
  • Code must not contain hardcoded credentials, secrets, or sensitive data

Testing Requirements

  • All code must have tests before being merged
  • Use JUnit for test execution
  • Use AssertJ for all assertions (JUnit assertions are forbidden)
  • Mockito allowed for mocking; prefer real objects when practical