Feature/667 fill in templates with defaults (#668)

* Prepare BaseConfig for usage in jinja templates
* Modify templates & add render code for output and diff
* Add information to the Dependencies documentation

Author: ArBridgeman

.import_linter_config

@@ -27,3 +27,4 @@ ignore_imports =
     # To reduce the effort in using nox sessions (i.e. having to pass the config path
     # in each CLI usage), we allow the noxconfig to be imported within these modules.
     exasol.toolbox.nox.* -> noxconfig
+    exasol.toolbox.tools.template -> noxconfig

doc/changes/unreleased.md

@@ -34,21 +34,22 @@ In previous versions, the default value for `poetry-version` was `2.1.2`, and it
 * Depending on its poetry version, a repository relying on the default behavior of said
 action may run into breaking changes. This can easily be resolved with explicitly setting the
 `poetry-version` when calling the GitHub action. It is, however, recommended whenever
-possible to update the poetry version of the affected repository. Unfortunately,
-there is not a quick and easy way to update all the places where `poetry-version`
-could be specified in the GitHub workflows.
+possible to update the poetry version of the affected repository. Since this major release,
+you can, if needed, alter the `poetry-version` via the `noxconfig.py::PROJECT_CONFIG`
+by changing `dependency_manager_version`. If you do this, please create an issue to
+update to `2.3.0` at your earliest convenience.
 
 * Projects migrating to this version should:
 
-* Update their `pyproject.toml` to have:
-    ```toml
-    requires-poetry = ">=2.3.0"
-    ```
-* Run `poetry check` and resolve any issues
-* (optional) Run `poetry lock` to update the  lock
-* (optional) Update their `pyproject.toml` to fit:
-   * [PEP-621](https://peps.python.org/pep-0621/)
-   * [PEP-735](https://peps.python.org/pep-0735/)
+  * Update their `pyproject.toml` to have:
+      ```toml
+      requires-poetry = ">=2.3.0"
+      ```
+  * Run `poetry check` and resolve any issues
+  * (optional) Run `poetry lock` to update the  lock
+  * (optional) Update their `pyproject.toml` to fit:
+     * [PEP-621](https://peps.python.org/pep-0621/)
+     * [PEP-735](https://peps.python.org/pep-0735/)
 
 Note that [uvx migrate-to-uv](https://github.com/mkniewallner/migrate-to-uv) seems to
 do a good job with automating many of the PEP-related changes; though developers should
@@ -65,6 +66,16 @@ take care and will need to make manual changes to ensure it still works with
 * #647: Added summary to changelog template
 * #657: Updated `release:prepare` to modify cookiecutter template exasol-toolbox version range
 * #665: Added SECURITY.md to the cookiecutter template
+* #667: Switched GitHub workflow templates to be controlled by PROJECT_CONFIG:
+   * The values in `BaseConfig.github_template_dict` are used to render the following values in
+     the templates
+      * `dependency_manager_version` - used for `poetry-version` in the workflows.
+         The default it `2.3.0`.
+      * `minimum_python_version` - used for `python-version` in the workflows whenever
+         `python-version` for actions that are run once. The default is the minimum value
+         in your project's defined `python_versions`
+      * `os_version` - used for the GitHub runner in the workflows. The default is
+         `ubuntu-24.04`
 
 ## Refactoring
 
@@ -74,3 +85,5 @@ take care and will need to make manual changes to ensure it still works with
   * `upload-pages-artifact` from v3 to [v4](https://github.com/actions/upload-pages-artifact/releases/tag/v4.0.0) - breaking change
   * `download-artifact`from v6 to [v7](https://github.com/actions/download-artifact/releases/tag/v7.0.0) - using Node.js 24
   * `upload-artifact` from v5 to [v6](https://github.com/actions/upload-artifact/releases/tag/v6.0.0) - using Node.js 24
+* #667: Added deprecation warnings to `tbx workflow x` endpoints as some are unneeded
+(will be removed) and others need updates (will be moved to a nox session)

doc/user_guide/dependencies.rst

@@ -1,9 +1,62 @@
 Dependencies
 ============
 
-Core dependencies
-+++++++++++++++++
+Core Dependencies
+-----------------
 
 - Python >= 3.10
-- poetry >= 2.3.0
+- `Poetry <https://python-poetry.org/docs/#installing-with-the-official-installer>`__ >= 2.3.0
   - `poetry export <https://github.com/python-poetry/poetry-plugin-export>`__
+
+Supported Poetry Versions by PTB
+--------------------------------
+
+.. list-table:: PTB Poetry Version Compatibility
+   :header-rows: 1
+
+   * - PTB Version
+     - Default in PTB
+     - Range Allowed
+     - Migration Information
+   * - >=1.0.0, <5.0.0
+     - 2.1.2
+     - >=2.1.0,<3.0
+     - None
+   * - >=5.0.0
+     - 2.3.0
+     - >=2.3.0,<3.0
+     - :ref:`migration_to_2.3.x`
+
+Migration Information
+---------------------
+
+.. _migration_to_2.3.x:
+
+From Poetry ``2.1.x`` to ``2.3.0``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+It is **highly** encouraged that a developer update their ``pyproject.toml`` and
+system-wide Poetry installation to most use effectively use Poetry ``2.3.0``:
+
+#. In your terminal, update your system-wide Poetry version:
+
+    .. code-block:: bash
+
+        poetry self update 2.3.0
+
+#. In your project's ``pyproject.toml``, update the ``requires-poetry`` value:
+
+    .. code-block:: toml
+
+        requires-poetry = ">=2.3.0"
+
+#. In your terminal, execute ``poetry check`` and resolve any listed issues
+#. In your terminal, run ``poetry lock`` to update the lock
+#. (optional but recommended) In your project's ``pyproject.toml``, update it to fit:
+    * `PEP-621 <https://peps.python.org/pep-0621/>`__
+    * `PEP-735 <https://peps.python.org/pep-0735/>`__
+
+    .. note::
+        Note that `uvx migrate-to-uv <https://github.com/mkniewallner/migrate-to-uv>`__
+        seems to do a good job with automating many of the PEP-related changes.
+        Though, a developer should take care to verify the changes, as some are unneeded
+        as it completes the migration to ``uv`` which the PTB does NOT yet support.

doc/user_guide/features/documentation/index.rst

@@ -9,7 +9,7 @@ Deploying documentation
     multiversion
     troubleshooting
 
-The PTB uses ref:`sphinx <https://www.sphinx-doc.org/>`__ to build and validate the contents
+The PTB uses `sphinx <https://www.sphinx-doc.org/>`__ to build and validate the contents
 of your project's documentation. PTB expects the project's documentation in directory ``doc``,
 primarily as ``rst`` files. The ``doc/conf.py`` acts as the configuration file for building the
 documentation.

exasol/toolbox/config.py

@@ -1,18 +1,23 @@
 import inspect
+import warnings
 from collections.abc import Callable
 from pathlib import Path
 from typing import (
     Annotated,
     Any,
+    Literal,
 )
 
+from packaging import version
 from pydantic import (
     AfterValidator,
     BaseModel,
     ConfigDict,
     Field,
     computed_field,
+    field_validator,
 )
+from pydantic_core.core_schema import ValidationInfo
 
 from exasol.toolbox.nox.plugin import (
     METHODS_SPECIFIED_FOR_HOOKS,
@@ -93,6 +98,26 @@ def valid_version_string(version_string: str) -> str:
 }
 
 
+class DependencyManager(BaseModel):
+    # Restricted to only allow "poetry" at the moment
+    name: Literal["poetry"]
+    version: ValidVersionStr
+
+    @field_validator("version")
+    @classmethod
+    def check_minimum_version(cls, v: str, info: ValidationInfo) -> str:
+        tool = info.data.get("name")
+        if tool == "poetry":
+            prefix = "Poetry version "
+            if version.parse(v) < (min_version := version.parse("2.1.4")):
+                raise ValueError(prefix + f"must be >= {min_version}")
+            elif version.parse(v) >= (max_version := version.parse("3.0.0")):
+                raise ValueError(prefix + f"must be < {max_version}")
+            elif version.parse(v) > (current_version := version.parse("2.3.0")):
+                warnings.warn(prefix + f"exceeds last tested version {current_version}")
+        return v
+
+
 class BaseConfig(BaseModel):
     """
     Basic configuration for projects using the PTB
@@ -142,6 +167,24 @@ class BaseConfig(BaseModel):
         possible plugin options are defined in `exasol.toolbox.nox.plugins.NoxTasks`.
         """,
     )
+    dependency_manager: DependencyManager = Field(
+        default=DependencyManager(name="poetry", version="2.3.0"),
+        description="""
+        This is used to define which dependency manager is used to install dependencies
+        in the CI. For more details on which PTB version pairs with which
+        dependency manager, see:
+            https://exasol.github.io/python-toolbox/main/user_guide/dependencies.html
+        """,
+    )
+    os_version: str = Field(
+        default="ubuntu-24.04",
+        pattern=r"^ubuntu-.*",
+        description="""
+        This is used to set the OS-runner in the GitHub workflows that are
+        provided as templates from the PTB. Currently, only ubuntu-based runners
+        are supported.
+        """,
+    )
     model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
 
     @computed_field  # type: ignore[misc]
@@ -222,3 +265,16 @@ def version_filepath(self) -> Path:
         the nox sessions ``version:check`` and ``release:prepare``.
         """
         return self.source_code_path / "version.py"
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def github_template_dict(self) -> dict[str, Any]:
+        """
+        Dictionary of variables to dynamically render Jinja2 templates into valid YAML
+        configurations.
+        """
+        return {
+            "dependency_manager_version": self.dependency_manager.version,
+            "minimum_python_version": self.minimum_python_version,
+            "os_version": self.os_version,
+        }

exasol/toolbox/templates/github/workflows/build-and-publish.yml

@@ -10,7 +10,7 @@ jobs:
 
   cd-job:
     name: Continuous Delivery
-    runs-on: ubuntu-24.04
+    runs-on: "(( os_version ))"
     permissions:
       contents: write
     steps:
@@ -19,6 +19,9 @@ jobs:
 
       - name: Setup Python & Poetry Environment
         uses: exasol/python-toolbox/.github/actions/python-environment@v4
+        with:
+          python-version: "(( minimum_python_version ))"
+          poetry-version: "(( dependency_manager_version ))"
 
       - name: Build Artifacts
         run: poetry build

exasol/toolbox/templates/github/workflows/check-release-tag.yml

@@ -7,7 +7,7 @@ jobs:
 
   check-tag-version-job:
     name: Check Tag Version
-    runs-on: ubuntu-24.04
+    runs-on: "(( os_version ))"
     permissions:
       contents: read
     steps:
@@ -16,6 +16,9 @@ jobs:
 
       - name: Setup Python & Poetry Environment
         uses: exasol/python-toolbox/.github/actions/python-environment@v4
+        with:
+          python-version: "(( minimum_python_version ))"
+          poetry-version: "(( dependency_manager_version ))"
 
       - name: Check Tag Version
         # make sure the pushed/created tag matched the project version