Skip to content

Latest commit

 

History

History
176 lines (126 loc) · 8.14 KB

CONTRIBUTING.adoc

File metadata and controls

176 lines (126 loc) · 8.14 KB
Raw

Contributing to Timefold Solver

This is an open source project, and you are more than welcome to contribute!

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: mvn clean install -Dquickly skips any checks and code analysis (~1 min)

  • 🔨 build-normally: mvn clean install runs tests, checks code style, skips documentation (~17 min)

  • 🧾 build-doc: mvn clean install in the docs directory creates asciidoctor documentation docs/target/html_single/index.html (~2 min)

  • 🦾 build-all: mvn clean install -Dfull runs all checks and creates documentation and distribution files (~20 min)

Build the Timefold Solver Python package

  • 🔨 build-fast: python -m build skips any checks and code analysis (~1 min)

  • 🦾 build-test: tox -e pyVERSION (for example, tox -e py310) runs tests against a given Python versions (~3 min)

  • 🦾 build-all: tox runs tests against all supported Python versions (~10 min)

Set up your development environment

  1. To develop with IntelliJ IDEA, Eclipse or VSCode, open the root pom.xml as a new project and configure a Run/Debug configuration like this:

    • Type: Application

    • Main class: ai.timefold.solver.examples.app.TimefoldExamplesApp

    • VM options: -Xmx2G (memory only needed when using the big datasets in the examples)

    • Program arguments: (none)

    • Working directory: $MODULE_DIR$ (must resolve to examples directory)

    • Use classpath of module: timefold-solver-examples

Code style

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

mvn clean install

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

Commit Messages

  • Use the present tense ("Add feature" not "Added feature")

  • Use the imperative mood ("Move cursor to…​" not "Moves cursor to…​")

  • Reference issues and pull requests liberally after the first line

We use Conventional Commits for PR titles and commit messages. The following prefixes are allowed:

  • feat for changes that add new features,

  • fix for changes that fix bugs,

  • docs for changes that only affect documentation,

  • perf for changes that improve performance,

  • test for adding missing tests or correcting existing tests,

  • build for changes that affect the build system or external dependencies,

  • ci for changes to our CI configuration files and scripts,

  • revert for reverting previous changes,

  • deps for updates to dependencies (mostly used by Dependabot),

  • chore for any other changes.

This convention is enforced by CI checks on pull requests.

Methodology overview

Development philosophy

Timefold Solver is developed in accordance with the following general principles:

  • Fail fast: Invalid states are checked as early as possible.

  • Understandable error message: Errors describe what happened and if possible, suggest solutions.

  • Consistent terminology: Names of features and components are not ambiguous and are used consistently throughout the codebase.

  • Real world usefulness: Every feature is used in an example or a quickstart. A feature is only delivered when tested and fully documented.

  • Automated testing: There are unit tests, integration tests, performance regressions tests and stress tests. The test coverage is high.

  • Good code hygiene: The code is clean, readable and understandable. Readability of code is preferred over ease of writing.

Package structure

The codebase of Timefold Solver is structured into three conceptual parts:

  • Public API, typically in a package with api somewhere in its name.

  • Configuration, typically in a package with config somewhere in its name.

  • Implementation, which is everything else.

The public API and configuration are the parts that we keep 100 % backwards compatible. Compatibility-breaking changes are only allowed in major versions of Timefold Solver, such as 2.0.0.

The implementation is out of bounds for users and it can and does change all the time. If users choose to depend on the implementation classes, they do so at their own risk.

Development guidelines

Fail fast

There are several levels of fail fast, from better to worse:

  1. Fail Fast at compile time. For example: Don’t accept an Object as a parameter if it needs to be a String or an Integer.

  2. Fail Fast at startup time. For example: if the configuration parameter needs to be a positive int and it’s negative, fail fast

  3. Fail Fast at runtime. For example: if the request needs to contain a double between 0.0 and 1.0 and it’s bigger than 1.0, fail fast.

  4. Fail Fast at runtime in assertion mode if the detection performance cost is high. For example: If, after every low level iteration, the variable A needs to be equal to the square root of B, check it if and only if an assert flag is set to true (usually controlled by the EnvironmentMode).

Exception messages

  1. The Exception message must include the name and state of each relevant variable. For example:

    if (fooSize < 0) {
    throw new IllegalArgumentException("The fooSize (" + fooSize + ") of bar (" + this + ") must be positive.");
}

    Notice that the output clearly explains what’s wrong:

    Exception in thread "main" java.lang.IllegalArgumentException: The fooSize (-5) of bar (myBar) must be positive.
    at ...

  2. Whenever possible, the Exception message must include context.

  3. Whenever the fix is not obvious, the Exception message should include advice. Advice normally starts with the word maybe on a new line:

    Exception in thread "main" java.lang.IllegalStateException: The valueRangeDescriptor (fooRange) is nullable, but not countable (false).
Maybe the member (getFooRange) should return CountableValueRange.
    at ...

    The word maybe is to indicate that the advice is not guaranteed to be right in all cases.

Generics

  1. The @PlanningSolution class is often passed as a generic type parameter to subsystems.

  2. The @PlanningEntity class(es) are rarely passed as a generic type parameter because there could be multiple planning entities.

Lifecycle

One of the biggest challenges in multi-algorithm implementations (such as Timefold Solver) is the lifecycle management of internal subsystems. These guidelines avoid lifecycle complexity:

  1. The subsystems are called in the same order in *Started() and *Ended methods.

    1. This avoids cyclic subsystem dependencies.

  2. The *Scope class’s fields are filled in piecemeal by the subsystems as the algorithms discover more information about its current scope subject.

    1. Therefore, a *Scope has mutable fields. It’s not an Event.

    2. A subsystem can only depend on scope information provided by an earlier subsystem.

  3. Global variables are sorted:

    1. First by volatility

    2. Then by initialization time