build: release version

.github/scripts/change_versions.sh

@@ -1,12 +1,17 @@
 #!/bin/bash
 
 # Expects the following environment variables to be set:
-#   $OLD_VERSION                 (Example: "1.1.0")
-#   $NEW_VERSION                 (Example: "1.2.0")
+#   $OLD_JAVA_VERSION                 (Example: "1.1.0")
+#   $NEW_JAVA_VERSION                 (Example: "1.2.0")
+#   $OLD_PYTHON_VERSION               (Example: "1.1.0b0")
+#   $NEW_PYTHON_VERSION               (Example: "1.2.0b0")
 
-echo "Old version: $OLD_VERSION"
-echo "New version: $NEW_VERSION"
+echo "Old Java version: $OLD_JAVA_VERSION"
+echo "Old Python version: $OLD_PYTHON_VERSION"
+echo "New Java version: $NEW_JAVA_VERSION"
+echo "New Python version: $NEW_PYTHON_VERSION"
 
 # Replaces the old version by the new version.
-find . -name pom.xml | xargs sed -i "s/>$OLD_VERSION</>$NEW_VERSION</g"
-find . -name build.gradle | xargs sed -i "s/\"$OLD_VERSION\"/\"$NEW_VERSION\"/g"
+find . -name pom.xml | xargs sed -i "s/>$OLD_JAVA_VERSION</>$NEW_JAVA_VERSION</g"
+find . -name build.gradle | xargs sed -i "s/\"$OLD_JAVA_VERSION\"/\"$NEW_JAVA_VERSION\"/g"
+find . -name pyproject.toml | xargs sed -i "s/timefold == $OLD_PYTHON_VERSION/timefold == $NEW_PYTHON_VERSION/g"

.github/scripts/run_python_tests.sh

@@ -0,0 +1,18 @@
+# Expects the following environment variables to be set:
+#     $TIMEFOLD_SOLVER_PYTHON_DIST    (Example: "/timefold-solver-python/dist")
+cd python || exit 1
+for d in */;
+do
+    if [ -f "$d/pyproject.toml" ]; then
+      cd "$d" || exit 1
+      if [ -d ".venv" ]; then
+          rm -rf .venv
+      fi
+      python -m venv .venv
+      . .venv/bin/activate
+      pip install --find-links "$TIMEFOLD_SOLVER_PYTHON_DIST" . || exit 1
+      pytest || exit 1
+      deactivate
+      cd .. || exit 1
+    fi
+done

.github/workflows/pull_request_gradle.yml

@@ -28,7 +28,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        module: ['hello-world', 'use-cases/school-timetabling', 'technology/java-spring-boot']
+        module: ['java/hello-world', 'java/school-timetabling', 'java/spring-boot-integration']
         java-version: [ 17 ] # Only the first supported LTS; already too many jobs here.
     timeout-minutes: 120
     steps:

.github/workflows/pull_request_long_running.yml

@@ -19,12 +19,12 @@ jobs:
     strategy:
       matrix:
         module: [
-          "technology/kotlin-quarkus", "use-cases/bed-allocation",
-          "use-cases/conference-scheduling", "use-cases/employee-scheduling", "use-cases/facility-location",
-          "use-cases/flight-crew-scheduling", "use-cases/food-packaging", "use-cases/maintenance-scheduling",
-          "use-cases/meeting-scheduling", "use-cases/order-picking", "use-cases/project-job-scheduling",
-          "use-cases/school-timetabling", "use-cases/sports-league-scheduling", "use-cases/task-assigning",
-          "use-cases/tournament-scheduling", "use-cases/vehicle-routing"
+          "kotlin/school-timetabling", "java/bed-allocation",
+          "java/conference-scheduling", "java/employee-scheduling", "java/facility-location",
+          "java/flight-crew-scheduling", "java/food-packaging", "java/maintenance-scheduling",
+          "java/meeting-scheduling", "java/order-picking", "java/project-job-scheduling",
+          "java/school-timetabling", "java/sports-league-scheduling", "java/task-assigning",
+          "java/tournament-scheduling", "java/vehicle-routing"
         ]
         java-version: [ 17 ] # Only the first supported LTS; already too many jobs here.
     timeout-minutes: 120
@@ -91,7 +91,7 @@ jobs:
     strategy:
       matrix:
         module: [
-          "technology/java-spring-boot"
+          "java/spring-boot-integration"
         ]
         java-version: [ 17 ] # Only the first supported LTS; already too many jobs here.
     timeout-minutes: 120

.github/workflows/pull_request_python.yml

@@ -0,0 +1,129 @@
+name: Python
+
+on:
+  push:
+    branches: [stable, development, '*.x']
+    paths:
+      - '**/*.py'
+      - '**/pyproject.toml'
+      - '.github/**/*.yml'
+  pull_request:
+    branches: [stable, development, '*.x']
+    paths:
+      - '**/*.py'
+      - '**/pyproject.toml'
+      - '.github/**/*.yml'
+
+jobs:
+  build:
+    concurrency:
+      group: pull_request_python-${{ github.event_name }}-${{ github.head_ref }}-${{ matrix.os }}-${{ matrix.java-version }}-${{ matrix.python-version }}
+      cancel-in-progress: true
+    runs-on: ${{matrix.os}}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macOS-latest]
+        java-version: [ 17 ] # Only the first supported LTS; already too many jobs here.
+        # TODO: Add Python 3.10 once employee scheduling and school timetabling support it
+        python-version: ['3.11', '3.12']
+    timeout-minutes: 120
+    steps:
+      # Clone timefold-solver
+      # Need to check for stale repo, since Github is not aware of the build chain and therefore doesn't automate it.
+      - name: Checkout timefold-solver (PR) # Checkout the PR branch first, if it exists
+        if: github.head_ref # Only true if this is a PR.
+        id: checkout-solver-pr
+        uses: actions/checkout@v4
+        continue-on-error: true
+        with:
+          repository: ${{ github.actor }}/timefold-solver
+          ref: ${{ github.head_ref }}
+          path: ./timefold-solver
+          fetch-depth: 0 # Otherwise merge will fail on account of not having history.
+      - name: Checkout timefold-solver (main) # Checkout the main branch if the PR branch does not exist
+        if: ${{ steps.checkout-solver-pr.outcome != 'success' }}
+        uses: actions/checkout@v4
+        with:
+          repository: TimefoldAI/timefold-solver
+          ref: main
+          path: ./timefold-solver
+          fetch-depth: 0 # Otherwise merge will fail on account of not having history.
+      - name: Prevent stale fork of timefold-solver # Solver can't be stale if development/stable branch requested.
+        if: ${{ steps.checkout-solver-pr.outcome == 'success' }}
+        env:
+          BLESSED_REPO: "timefold-solver"
+          BLESSED_BRANCH: ${{ endsWith(github.head_ref, '.x') && github.head_ref || 'main' }}
+        shell: bash
+        working-directory: ./timefold-solver
+        run: .github/scripts/prevent_stale_fork.sh
+
+      # Clone timefold-solver-python
+      # Need to check for stale repo, since Github is not aware of the build chain and therefore doesn't automate it.
+      - name: Checkout timefold-solver-python (PR) # Checkout the PR branch first, if it exists
+        if: github.head_ref # Only true if this is a PR.
+        id: checkout-solver-python-pr
+        uses: actions/checkout@v4
+        continue-on-error: true
+        with:
+          repository: ${{ github.actor }}/timefold-solver-python
+          ref: ${{ github.head_ref }}
+          path: ./timefold-solver-python
+          fetch-depth: 0 # Otherwise merge will fail on account of not having history.
+      - name: Checkout timefold-solver-python (main) # Checkout the main branch if the PR branch does not exist
+        if: ${{ steps.checkout-solver-python-pr.outcome != 'success' }}
+        uses: actions/checkout@v4
+        with:
+          repository: TimefoldAI/timefold-solver-python
+          ref: main
+          path: ./timefold-solver-python
+          fetch-depth: 0 # Otherwise merge will fail on account of not having history.
+      - name: Prevent stale fork of timefold-solver-python # Solver can't be stale if development/stable branch requested.
+        if: ${{ steps.checkout-solver-python-pr.outcome == 'success' }}
+        env:
+          BLESSED_REPO: "timefold-solver-python"
+          BLESSED_BRANCH: ${{ endsWith(github.head_ref, '.x') && github.head_ref || 'main' }}
+        shell: bash
+        working-directory: ./timefold-solver-python
+        run: ../timefold-solver/.github/scripts/prevent_stale_fork.sh
+
+      # Clone timefold-quickstarts
+      # No need to check for stale repo, as Github merges the main repo into the fork automatically.
+      - name: Checkout timefold-quickstarts
+        uses: actions/checkout@v4
+        with:
+          path: './timefold-quickstarts'
+
+      # Build and test
+      - name: "Setup Java and Maven"
+        uses: actions/setup-java@v3
+        with:
+          java-version: ${{matrix.java-version}}
+          distribution: 'temurin'
+          cache: 'maven'
+
+      - name: Python Setup
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{matrix.python-version}}
+          cache: 'pip'
+          cache-dependency-path: |
+            **/pyproject.toml
+
+      - name: Install build
+        run:
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Quickly build timefold-solver
+        working-directory: ./timefold-solver
+        run: mvn -B -Dquickly -DskipTests clean install
+
+      - name: Build timefold-solver-python
+        working-directory: ./timefold-solver-python
+        run: python -m build
+
+      - name: Build and test timefold-quickstarts
+        working-directory: ./timefold-quickstarts
+        env:
+          TIMEFOLD_SOLVER_PYTHON_DIST: "${{ github.workspace }}/timefold-solver-python/dist"
+        run: .github/scripts/run_python_tests.sh

.github/workflows/release.yml

@@ -2,9 +2,12 @@ name: Release
 on:
   workflow_dispatch:
     inputs:
-      version:
+      java-version:
         description: 'Community Edition version (e.g. 1.0.0)'
         required: true
+      python-version:
+        description: 'Python Community Edition version (e.g. 1.0.0b0)'
+        required: true
       developmentBranch:
         description: 'Development branch to cut the release from'
         default: development
@@ -45,12 +48,14 @@ jobs:
           git config user.name "Timefold Release Bot"
           git config user.email "[email protected]"
           git checkout -B ${{ github.event.inputs.releaseBranch }}
-          export OLD_VERSION="$(find . -name pom.xml -exec grep '<version.ai.timefold.solver>' {} \;|tail -n 1|cut -d\> -f1 --complement|cut -d\< -f1)"
-          export NEW_VERSION="${{ github.event.inputs.version }}"
+          export OLD_JAVA_VERSION="$(find . -name pom.xml -exec grep '<version.ai.timefold.solver>' {} \;|tail -n 1|cut -d\> -f1 --complement|cut -d\< -f1)"
+          export NEW_JAVA_VERSION="${{ github.event.inputs.java-version }}"
+          export OLD_PYTHON_VERSION="$(find . -name pyproject.toml -exec grep 'timefold ==' {} \;|tail -n 1|cut -d\' -f1 --complement|cut -d\= -f3|cut -d\' -f1|xargs)"
+          export NEW_PYTHON_VERSION="${{ github.event.inputs.python-version }}"
           .github/scripts/change_versions.sh
           mvn verify
           git commit -am "build: switch to version $NEW_VERSION"
-          git tag -a "v${{ github.event.inputs.version }}" -m "Release version ${{ github.event.inputs.version }}"
+          git tag -a "v${{ github.event.inputs.java-version }}" -m "Release version ${{ github.event.inputs.java-version }}"
           git push --tags
 
       # Merge the release branch into the stable branch.
@@ -73,8 +78,10 @@ jobs:
       - name: Put back the 999-SNAPSHOT version on the release branch
         run: |
           git checkout ${{ github.event.inputs.releaseBranch }}
-          export OLD_VERSION="$(find . -name pom.xml -exec grep '<version.ai.timefold.solver>' {} \;|tail -n 1|cut -d\> -f1 --complement|cut -d\< -f1)"
-          export NEW_VERSION="999-SNAPSHOT"
+          export OLD_JAVA_VERSION="$(find . -name pom.xml -exec grep '<version.ai.timefold.solver>' {} \;|tail -n 1|cut -d\> -f1 --complement|cut -d\< -f1)"
+          export NEW_JAVA_VERSION="999-SNAPSHOT"
+          export OLD_PYTHON_VERSION="$(find . -name pyproject.toml -exec grep 'timefold ==' {} \;|tail -n 1|cut -d\' -f1 --complement|cut -d\= -f3|cut -d\' -f1|xargs)"
+          export NEW_PYTHON_VERSION="999-dev0"
           .github/scripts/change_versions.sh
           git commit -am "build: move back to version $NEW_VERSION"
           git push origin ${{ github.event.inputs.releaseBranch }}

.gitignore

@@ -14,5 +14,10 @@ build
 *.iws
 *.iml
 
+# Python files
+__pycache__
+.venv
+venv*
+
 # Repository wide ignore mac DS_Store files
 .DS_Store

CONTRIBUTING.adoc

@@ -0,0 +1,48 @@
+== Contributing to Timefold Quickstarts
+
+This is an open source project, and you are more than welcome to contribute!
+
+* Found an issue? https://github.com/TimefoldAI/timefold-quickstarts/issues[Submit an issue.]
+* Want to fix an issue or contribute an improvement? https://github.com/TimefoldAI/timefold-solver/discussions[Talk to us about your ideas] or just start coding:
+
+. https://github.com/TimefoldAI/timefold-quickstarts/fork[Fork it.]
+. Create a feature branch: `git checkout -b feature`
+. Commit your changes with a comment: `git commit -m "feat: add shiny new feature"`
+(See xref:commit-messages[Commit messages] for details.)
+. Push to the branch to GitHub: `git push origin feature`
+. https://github.com/TimefoldAI/timefold-quickstarts/compare/development...development[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.
+
+
+=== Developing Python quickstarts
+
+The Python quickstarts on the `development` branch uses the
+development `999-dev0` build of `timefold-solver`.
+This needs to be built locally:
+
+. Clone https://github.com/TimefoldAI/timefold-solver-python[timefold-solver-python].
+
+. Install `build`
++
+[source,base]
+----
+$ pip install build
+----
+
+. Build the main branch of `timefold-solver-python`
++
+[source,base]
+----
+$ python -m build
+----
+
+. Reference the `timefold-solver-python` build directory in your `~/.config/pip/pip.conf`:
++
+[source,ini]
+----
+[global]
+find-links =
+    /path/to/timefold-solver-python/dist
+----