sequential-parameter-optimization · bartzbeielstein · Mar 30, 2026 · Mar 30, 2026 · Mar 30, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -13,6 +13,11 @@ on:
 # Principle of Least Privilege: Base permissions are read-only
 permissions: read-all
 
+# Cancel stale runs when a new push arrives on the same branch or PR.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   reuse:
     name: REUSE Compliance

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -19,8 +19,7 @@ name: Documentation
 on:
   push:
     branches:
-      - main
-      - develop
+      - main        # Production docs only; develop pushes are not deployed.
     paths:
       - '**/*.qmd'
       - '_quarto.yml'
@@ -30,6 +29,12 @@ on:
 
 permissions: read-all
 
+# Prevent concurrent deployments from overwriting each other on gh-pages.
+# A docs build can take several minutes; let it finish rather than cancel.
+concurrency:
+  group: docs-deploy
+  cancel-in-progress: false
+
 env:
   # ⚠️ Pinned to match production safety standards.
   QUARTO_VERSION: "1.8.27"

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -9,6 +9,11 @@ on:
 # Principle of Least Privilege: Base permissions are read-only
 permissions: read-all
 
+# Serialize releases per-branch; never cancel an in-progress release.
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
 jobs:
   release:
     name: Create Release
@@ -129,3 +134,74 @@ jobs:
               sleep 10
             fi
           done
+
+  # ---------------------------------------------------------------------------
+  # Back-merge: keep develop in sync after every main release
+  # ---------------------------------------------------------------------------
+  # Why: semantic-release commits CHANGELOG.md + pyproject.toml back to main.
+  # Without this job, develop diverges and the next develop→main PR conflicts.
+  # Strategy: use the built-in GITHUB_TOKEN (no extra secret needed) to open a
+  # PR via the pre-installed `gh` CLI. If branch-protection requires a review
+  # the PR waits; otherwise it can be auto-merged by the repo owner. The step
+  # is idempotent: if main is already merged into develop, or a PR already
+  # exists, it exits gracefully.
+  back-merge:
+    name: Back-merge main → develop
+    runs-on: ubuntu-latest
+    needs: release
+    # Only needed after production releases on main, not for rc on develop.
+    if: github.ref == 'refs/heads/main'
+    permissions:
+      contents: write       # required to push/read branches
+      pull-requests: write  # required to open the PR
+
+    steps:
+      - name: Checkout (full history)
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          fetch-depth: 0
+          # Use the default GITHUB_TOKEN; gh CLI picks it up via GH_TOKEN below.
+
+      - name: Check whether a back-merge is needed
+        id: sync-check
+        run: |
+          git fetch origin develop
+          AHEAD=$(git rev-list --count origin/develop..HEAD)
+          echo "main is ${AHEAD} commit(s) ahead of develop"
+          echo "needed=${AHEAD}" >> "$GITHUB_OUTPUT"
+
+      - name: Open back-merge PR (main → develop)
+        if: steps.sync-check.outputs.needed != '0'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION=$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
+
+          # Idempotency: skip if an open PR already targets develop from main.
+          EXISTING=$(gh pr list \
+            --base develop --head main \
+            --state open \
+            --json number \
+            --jq '.[0].number' 2>/dev/null || true)
+
+          if [ -n "$EXISTING" ]; then
+            echo "Back-merge PR #${EXISTING} already open. Nothing to do."
+            exit 0
+          fi
+
+          gh pr create \
+            --base develop \
+            --head main \
+            --title "chore: back-merge release ${VERSION} (main → develop)" \
+            --body "$(cat <<'EOF'
+          Automated back-merge created by the Release workflow.
+
+          Release ${VERSION} committed updated files (CHANGELOG.md, pyproject.toml)
+          back to main. This PR syncs those changes into develop so the next
+          develop → main pull request has no conflicts.
+
+          Merge this PR as soon as convenient.
+          EOF
+          )"
+
+          echo "✓ Back-merge PR created for release ${VERSION}"
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,23 @@
+## <small>0.1.2-rc.1 (2026-03-30)</small>
+
+* Merge branch 'main' into dependabot/uv/authlib-1.6.9 ([068affd](https://github.com/sequential-parameter-optimization/spotdesirability/commit/068affd))
+* Merge branch 'main' into develop ([54d1b82](https://github.com/sequential-parameter-optimization/spotdesirability/commit/54d1b82))
+* Merge pull request #24 from sequential-parameter-optimization/dependabot/uv/authlib-1.6.9 ([a108d39](https://github.com/sequential-parameter-optimization/spotdesirability/commit/a108d39)), closes [#24](https://github.com/sequential-parameter-optimization/spotdesirability/issues/24)
+* Merge pull request #25 from sequential-parameter-optimization/dependabot/github_actions/actions-ffd1 ([4172ca7](https://github.com/sequential-parameter-optimization/spotdesirability/commit/4172ca7)), closes [#25](https://github.com/sequential-parameter-optimization/spotdesirability/issues/25)
+* Merge pull request #26 from sequential-parameter-optimization/dependabot/uv/requests-2.33.0 ([5975db4](https://github.com/sequential-parameter-optimization/spotdesirability/commit/5975db4)), closes [#26](https://github.com/sequential-parameter-optimization/spotdesirability/issues/26)
+* Merge pull request #27 from sequential-parameter-optimization/dependabot/pip/python-deps-d0a4681fe4 ([e0a6543](https://github.com/sequential-parameter-optimization/spotdesirability/commit/e0a6543)), closes [#27](https://github.com/sequential-parameter-optimization/spotdesirability/issues/27)
+* Merge pull request #28 from sequential-parameter-optimization/dependabot/uv/cryptography-46.0.6 ([24f3105](https://github.com/sequential-parameter-optimization/spotdesirability/commit/24f3105)), closes [#28](https://github.com/sequential-parameter-optimization/spotdesirability/issues/28)
+* Merge pull request #30 from sequential-parameter-optimization/dependabot/uv/nltk-3.9.4 ([747233f](https://github.com/sequential-parameter-optimization/spotdesirability/commit/747233f)), closes [#30](https://github.com/sequential-parameter-optimization/spotdesirability/issues/30)
+* Merge pull request #32 from sequential-parameter-optimization/dependabot/uv/pygments-2.20.0 ([401b0ce](https://github.com/sequential-parameter-optimization/spotdesirability/commit/401b0ce)), closes [#32](https://github.com/sequential-parameter-optimization/spotdesirability/issues/32)
+* fix: compressor data and qquartodoc (with README) ([7a4e661](https://github.com/sequential-parameter-optimization/spotdesirability/commit/7a4e661))
+* chore(deps-dev): update uv-build requirement in the python-deps group ([b0cf6a8](https://github.com/sequential-parameter-optimization/spotdesirability/commit/b0cf6a8))
+* chore(deps): bump authlib from 1.6.8 to 1.6.9 ([266e37c](https://github.com/sequential-parameter-optimization/spotdesirability/commit/266e37c))
+* chore(deps): bump cryptography from 46.0.5 to 46.0.6 ([ce97b7c](https://github.com/sequential-parameter-optimization/spotdesirability/commit/ce97b7c))
+* chore(deps): bump nltk from 3.9.3 to 3.9.4 ([663cc10](https://github.com/sequential-parameter-optimization/spotdesirability/commit/663cc10))
+* chore(deps): bump pygments from 2.19.2 to 2.20.0 ([9e8ff43](https://github.com/sequential-parameter-optimization/spotdesirability/commit/9e8ff43))
+* chore(deps): bump requests from 2.32.5 to 2.33.0 ([4eb6f40](https://github.com/sequential-parameter-optimization/spotdesirability/commit/4eb6f40))
+* chore(deps): bump the actions group across 1 directory with 5 updates ([68c0ae1](https://github.com/sequential-parameter-optimization/spotdesirability/commit/68c0ae1))
+
 ## <small>0.1.1 (2026-03-30)</small>
 
 * Merge branch 'main' into develop ([28fd17d](https://github.com/sequential-parameter-optimization/spotdesirability/commit/28fd17d))

diff --git a/README.md b/README.md
@@ -70,8 +70,53 @@ Alternatively, you can clone the repository and install it manually.
 
 ## Documentation
 
+### Availability
+
 The documentation is available at: [https://sequential-parameter-optimization.github.io/spotdesirability/](https://sequential-parameter-optimization.github.io/spotdesirability/)
 
+### Local Build
+
+It can be built locally using `quartodoc`  als follows:
+
+```bash
+# Step 1 — Regenerate the API reference .qmd stubs from docstrings
+uv run python docs/quartodoc_build.py
+uv run quartodoc interlinks
+
+# Step 2 — Render the full site
+uv run quarto render --no-cache
+
+# Output lands in _site/index.html
+```
+
+### Add New Functions, Classes, or Methods
+
+
+1. Write the function with a Google-style docstring
+2. Add it to _quarto.yml → quartodoc.sections[].contents
+3. Add it to _quarto.yml → website.sidebar[].contents
+4. Run (as above): uv run python docs/quartodoc_build.py && uv run quartodoc interlinks
+5. Run (as above): uv run quarto render --no-cache
+
+Here is an example how to modify `_quarto.yml`:
+
+```yaml
+# quartodoc section (stub generation)
+- title: "Data Utilities"
+  contents:
+    - data_utils
+    - data_utils.get_data_folder_path
+    - data_utils.load_compressor_data   # ← added
+
+# sidebar nav
+- section: "Data Utilities"
+  contents:
+    - text: "load_compressor_data"      # ← added
+      file: docs/reference/data_utils.load_compressor_data.qmd
+```
+
+Note: The `file` entry matches the path in the `src` folder, where the Python code is located. Only add `.qmd` to the file name and replace the `/` with `.`. Then add `docs/reference/` in front of the file name.
+
 
 ## Citation
 

diff --git a/_inv/python_objects.json b/_inv/python_objects.json
diff --git a/_quarto.yml b/_quarto.yml
@@ -132,6 +132,8 @@ website:
                 file: docs/reference/data_utils.qmd
               - text: "get_data_folder_path"
                 file: docs/reference/data_utils.get_data_folder_path.qmd
+              - text: "load_compressor_data"
+                file: docs/reference/data_utils.load_compressor_data.qmd
 
   # ── Page footer ───────────────────────────────────────────────────────────
   page-footer:
@@ -208,3 +210,4 @@ quartodoc:
       contents:
         - data_utils
         - data_utils.get_data_folder_path
+        - data_utils.load_compressor_data
diff --git a/docs/reference/data_utils.load_compressor_data.qmd b/docs/reference/data_utils.load_compressor_data.qmd
@@ -0,0 +1,33 @@
+# data_utils.load_compressor_data { #spotdesirability.data_utils.load_compressor_data }
+
+```python
+data_utils.load_compressor_data()
+```
+
+Loads the normalized compressor datasets X and Z.
+
+This function reads df_x_normalized.csv and df_z_normalized.csv from the
+spotdesirability.datasets module and returns them as pandas DataFrames.
+The datasets represent the values of $X$ and $Z$ respectively.
+
+## Returns {.doc-section .doc-section-returns}
+
+| Name   | Type                                           | Description                                                                |
+|--------|------------------------------------------------|----------------------------------------------------------------------------|
+|        | [pd](`pandas`).[DataFrame](`pandas.DataFrame`) | Tuple[pd.DataFrame, pd.DataFrame]: A tuple containing the datasets X and Z |
+|        | [pd](`pandas`).[DataFrame](`pandas.DataFrame`) | as pandas DataFrames respectively.                                         |
+
+## Raises {.doc-section .doc-section-raises}
+
+| Name   | Type                                     | Description                                |
+|--------|------------------------------------------|--------------------------------------------|
+|        | [FileNotFoundError](`FileNotFoundError`) | If the datasets cannot be found.           |
+|        | [RuntimeError](`RuntimeError`)           | If there is an issue reading the CSV data. |
+
+## Example {.doc-section .doc-section-example}
+
+```{python}
+import spotdesirability.data_utils as du
+
+df_x, df_z = du.load_compressor_data()
+```
diff --git a/docs/reference/data_utils.qmd b/docs/reference/data_utils.qmd
@@ -8,4 +8,5 @@
 
 | Name | Description |
 | --- | --- |
-| [](`~spotdesirability.data_utils.get_data_folder_path`) | Returns the absolute path to the data folder located in the package. |
+| [](`~spotdesirability.data_utils.get_data_folder_path`) | Returns the absolute path to the data folder located in the package. |
+| [](`~spotdesirability.data_utils.load_compressor_data`) | Loads the normalized compressor datasets X and Z. |
diff --git a/docs/reference/index.qmd b/docs/reference/index.qmd
@@ -38,4 +38,5 @@
 | | |
 | --- | --- |
 | [data_utils](data_utils.qmd#spotdesirability.data_utils) |  |
-| [data_utils.get_data_folder_path](data_utils.get_data_folder_path.qmd#spotdesirability.data_utils.get_data_folder_path) | Returns the absolute path to the data folder located in the package. |
+| [data_utils.get_data_folder_path](data_utils.get_data_folder_path.qmd#spotdesirability.data_utils.get_data_folder_path) | Returns the absolute path to the data folder located in the package. |
+| [data_utils.load_compressor_data](data_utils.load_compressor_data.qmd#spotdesirability.data_utils.load_compressor_data) | Loads the normalized compressor datasets X and Z. |