From a625c73fa13937381b6953af5a6b6831c7bbf4e8 Mon Sep 17 00:00:00 2001 From: Sebastien Morais Date: Mon, 28 Apr 2025 11:17:54 +0200 Subject: [PATCH 1/3] docs: use pinned dependencies in CICD --- doc/source/how-to/continuous-integration.rst | 66 ++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/doc/source/how-to/continuous-integration.rst b/doc/source/how-to/continuous-integration.rst index 9652aed04..397169c0f 100644 --- a/doc/source/how-to/continuous-integration.rst +++ b/doc/source/how-to/continuous-integration.rst @@ -183,3 +183,69 @@ Workflow examples are provided for various checks, such as :ref:`code style `_. + of the project itself. + +To guarantee reproducibility, stability, and predictability of workflows, it is critical that +CI uses a locked, fully resolved list of pinned versions. If a project allows floating +versions of dependencies, for example `numpy>=1.26`, to be used in CI, it is exposed to random +failures without any code change. In fact, problems can occur at different levels: + +- Runtime bugs: Update in runtime dependencies, like `numpy` or `pandas`, can introduce changes + in API behavior, deprecations, or regressions, affecting production code. +- Test failures: A minor update of a testing library could introduce breaking changes or + modify test behavior, causing false negatives or false positives. +- Documentation build breaks: A documentation generator like `Sphinx` might introduce + subtle or breaking changes, like new warnings treated as errors or theme updates breaking + rendering, causing your docs build to fail. + +Pinning dependencies avoid these issues by freezing exact versions and ensure that CI +workflows are reliable and predictable. + +Additionally, having a complete, pinned set of dependencies is very useful for users and +contributors. If an user encounters issues while running tests locally, using the frozen +dependencies from CI could fix the problems or provide a reproducible environment for debugging. +Overall, this improves support, debugging speed, and community contribution experience. + +How to pin dependencies +----------------------- + +Depending on the type of project, different tools can be used to manage and pin dependencies. +In the following, we assume that your project has defined +`optional installation targets `_ +to illustrate how to install specific subsets of dependencies. + +If you are using `poetry `_, you can use the ``poetry lock`` +command to generate a ``poetry.lock`` file with all the dependencies and their versions. +Once the lock file created, you can use the following command in your CI workflow to install +the project with `tests` dependencies: + +.. code-block:: yaml + + - name: Install dependencies with extra tests + run: | + poetry install --with tests + +If your project uses `flit` or `hatch`, you can use `uv `_ +to fastly resolve the dependencies and generate a requirements file. You can use the +``uv pip compile -o requirements.txt pyproject.toml`` command to generate a ``requirements.txt`` +file with the main dependencies defined in your project. Note that, contrary to the +``poetry.lock`` file, the requirements file does not include the variations for each installation +target. To create a requirements file with a specific extra, you can use the ``--extras`` option. +For example, you can create a requirement file with the `tests` extra by running the +``uv pip compile --extra tests -o requirements-tests.txt pyproject.toml``. Once the file created, +you can use the following command in your CI workflow to install the project with `tests` +dependencies: + +.. code-block:: yaml + + - name: Install dependencies with extra tests + run: | + pip install -r requirements-tests.txt From 1d356e7e80c91646df6f6b8b1d87043a9a0bdb14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Morais?= <146729917+SMoraisAnsys@users.noreply.github.com> Date: Mon, 28 Apr 2025 13:13:11 +0200 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Doug Addy --- doc/source/how-to/continuous-integration.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/source/how-to/continuous-integration.rst b/doc/source/how-to/continuous-integration.rst index 397169c0f..08ad626ad 100644 --- a/doc/source/how-to/continuous-integration.rst +++ b/doc/source/how-to/continuous-integration.rst @@ -189,7 +189,7 @@ Importance of pinned dependencies .. note:: - This guidance applies to CI workflows. It does apply to the + This guidance applies to CI workflows. It does not apply to the `dependency version range `_. of the project itself. @@ -202,11 +202,11 @@ failures without any code change. In fact, problems can occur at different level in API behavior, deprecations, or regressions, affecting production code. - Test failures: A minor update of a testing library could introduce breaking changes or modify test behavior, causing false negatives or false positives. -- Documentation build breaks: A documentation generator like `Sphinx` might introduce +- Documentation build failures: A documentation generator like `Sphinx` might introduce subtle or breaking changes, like new warnings treated as errors or theme updates breaking rendering, causing your docs build to fail. -Pinning dependencies avoid these issues by freezing exact versions and ensure that CI +Pinning dependencies helps to avoid these issues by freezing exact versions and ensuring that CI workflows are reliable and predictable. Additionally, having a complete, pinned set of dependencies is very useful for users and @@ -234,13 +234,13 @@ the project with `tests` dependencies: poetry install --with tests If your project uses `flit` or `hatch`, you can use `uv `_ -to fastly resolve the dependencies and generate a requirements file. You can use the +to resolve the dependencies and generate a requirements file. You can use the ``uv pip compile -o requirements.txt pyproject.toml`` command to generate a ``requirements.txt`` -file with the main dependencies defined in your project. Note that, contrary to the +file with the main dependencies defined in your project. Note that, unlike the ``poetry.lock`` file, the requirements file does not include the variations for each installation target. To create a requirements file with a specific extra, you can use the ``--extras`` option. For example, you can create a requirement file with the `tests` extra by running the -``uv pip compile --extra tests -o requirements-tests.txt pyproject.toml``. Once the file created, +``uv pip compile --extra tests -o requirements-tests.txt pyproject.toml``. Once the file has been created, you can use the following command in your CI workflow to install the project with `tests` dependencies: From f0f73e5aaffd4e8115b75677f61845269f413e2f Mon Sep 17 00:00:00 2001 From: Sebastien Morais Date: Mon, 28 Apr 2025 14:40:46 +0200 Subject: [PATCH 3/3] fix(docs): handle vale warnings --- doc/source/how-to/continuous-integration.rst | 2 +- doc/styles/config/vocabularies/ANSYS/accept.txt | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/source/how-to/continuous-integration.rst b/doc/source/how-to/continuous-integration.rst index 08ad626ad..f4d322b37 100644 --- a/doc/source/how-to/continuous-integration.rst +++ b/doc/source/how-to/continuous-integration.rst @@ -218,7 +218,7 @@ How to pin dependencies ----------------------- Depending on the type of project, different tools can be used to manage and pin dependencies. -In the following, we assume that your project has defined +In the following, this guidance assumes that your project has defined `optional installation targets `_ to illustrate how to install specific subsets of dependencies. diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt index 8a7f62a83..028d1051b 100644 --- a/doc/styles/config/vocabularies/ANSYS/accept.txt +++ b/doc/styles/config/vocabularies/ANSYS/accept.txt @@ -116,6 +116,7 @@ untracked untrusted unvalidated URIs +uv Vale venv Visual Studio Code