refactor: manage pdm and pre-commit with make prerequisites (#637)

.devcontainer/Dockerfile

@@ -17,6 +17,11 @@ ENV PYTHONDONTWRITEBYTECODE=1
 ENV PYTHONHASHSEED=0
 ENV PYTHONUNBUFFERED=1
 
+# Config pipx
+ENV PIPX_HOME=/usr/local/pipx
+ENV PIPX_BIN_DIR=/usr/local/bin
+ENV PIPX_DEFAULT_PYTHON=/usr/local/bin/python
+
 # renovate: depName=debian_12/bash-completion
 ARG BASH_COMPLETION_VERSION="1:2.11-6"
 # renovate: depName=debian_12/pipx
@@ -26,27 +31,17 @@ ARG SUDO_VERSION="1.9.13p3-1+deb12u1"
 # renovate: depName=debian_12/vim
 ARG VIM_VERSION="2:9.0.1378-2"
 
+# Install system dependencies and override pipx with a newer version
 RUN apt-get update && apt-get install -y --no-install-recommends \
     bash-completion="${BASH_COMPLETION_VERSION}" \
     pipx="${PIPX_VERSION}" \
     sudo="${SUDO_VERSION}" \
     vim="${VIM_VERSION}" \
-    && apt-get clean -y && rm -rf /var/lib/apt/lists/*
-
-# Config pipx
-ENV PIPX_HOME=/usr/local/pipx
-ENV PIPX_BIN_DIR=/usr/local/bin
-ENV PIPX_DEFAULT_PYTHON=/usr/local/bin/python
-
-# Install pdm
-RUN pipx install pdm==2.16.1
-
-# Install pre-commit
-RUN if [ "${PYTHON_VERSION}" = "3.8" ]; then \
-        pipx install pre-commit==3.5.0; \
-    else \
-        pipx install pre-commit==3.7.1; \
-    fi
+    && pipx install pipx==1.6.0 \
+    && apt-get purge -y --autoremove pipx \
+    && apt-get clean -y \
+    && rm -rf /var/lib/apt/lists/* \
+    && hash -r
 
 # Install prerequisites
 RUN --mount=source=Makefile,target=Makefile \

.renovaterc.json

@@ -29,7 +29,7 @@
             ],
             "matchStrings": [
                 "pip install.* (?<depName>.*?)==(?<currentValue>.*?)[\"\n]",
-                "pipx install (?<depName>.*?)==(?<currentValue>.*?)[;\n]"
+                "pipx install( --force)? (?<depName>.*?)==(?<currentValue>.*?)\n"
             ]
         },
         {

Makefile

@@ -7,6 +7,9 @@
 # Documentation target directory, will be adapted to specific folder for readthedocs.
 PUBLIC_DIR := $(shell [ "$$READTHEDOCS" = "True" ] && echo "$${READTHEDOCS_OUTPUT}html" || echo "public")
 
+# Determine the Python version used by pipx.
+PIPX_PYTHON_VERSION := $(shell `pipx environment --value PIPX_DEFAULT_PYTHON` -c "from sys import version_info; print(f'{version_info.major}.{version_info.minor}')")
+
 ########################################################################################
 # Development Environment Management
 ########################################################################################
@@ -53,6 +56,12 @@ dev:
 
 # Install standalone tools
 prerequisites:
+	pipx install --force pdm==2.16.1
+ifeq ($(PIPX_PYTHON_VERSION), 3.8)
+	pipx install --force pre-commit==3.5.0
+else
+	pipx install --force pre-commit==3.7.1
+endif
 	pipx install --force pyproject-fmt==2.1.4
 	pipx install --force ruff==0.5.0
 

README.md

@@ -57,15 +57,12 @@ If you find this helpful, please consider [sponsorship](https://github.com/spons
 
 ## 🔧 Prerequisites
 
-Certain system-level Python applications are needed and it is recommended to use [pipx](https://pypa.github.io/pipx/) to install and run them in isolated environments. Refer to pipx's installation instructions [here](https://pypa.github.io/pipx/installation/). Once `pipx` is set up, install the necessary tools using the following commands.
+[pipx](https://pipx.pypa.io/) is required to manage the standalone tools used across the development lifecycle.
+Please refer to pipx's installation instructions [here](https://pipx.pypa.io/stable/installation/).
+Once pipx is set up, install the copier for project generation using the following command:
 
 ```bash
-# Copier: Template rendering for projects.
 pipx install copier==9.2.0
-# PDM: A modern Python package and dependency manager supporting the latest PEP standards.
-pipx install pdm==2.16.1
-# Pre-commit: Automates Git hooks for code quality checks.
-pipx install pre-commit==3.7.1
 ```
 
 ## 🚀 Quickstart
@@ -76,27 +73,33 @@ pipx install pre-commit==3.7.1
    copier copy gh:serious-scaffold/ss-python /path/to/project
    ```
 
-2. Navigate to the project directory and initialize a git repository.
+1. Navigate to the project directory and initialize a git repository.
 
    ```bash
    cd /path/to/project
    git init
    ```
 
-3. Set up the development environment.
+1. Install standalone tools.
+
+   ```bash
+   make prerequisites
+   ```
+
+1. Set up the development environment.
 
    ```bash
    make dev
    ```
 
-4. Commit the initialized project.
+1. Commit the initialized project.
 
    ```bash
    git add .
    git commit -m "Initialize from serious-scaffold."
    ```
 
-5. That's it! Feel free to focus on the coding within `src` folder.
+1. That's it! Feel free to focus on the coding within `src` folder.
 
 ## 📜 License
 

docs/development/setup-dev-env.md

@@ -4,17 +4,12 @@ This page shows the approach to set up development environment. To simplify the
 
 ## Prerequisites
 
-Several necessary tools need to be installed with the following commands:
-
-```{note}
-Using `pipx` for management is recommended and you can find pipx's installation instructions [here](https://pypa.github.io/pipx/installation/).
-```
+[pipx](https://pipx.pypa.io/) is required to manage the standalone tools used across the development lifecycle.
+Please refer to pipx's installation instructions [here](https://pipx.pypa.io/stable/installation/).
+Once pipx is set up, install the needed standalone tools with the following command:
 
 ```bash
-# PDM: A modern Python package and dependency manager supporting the latest PEP standards.
-pipx install pdm==2.16.1
-# Pre-commit: Automates Git hooks for code quality checks.
-pipx install pre-commit==3.7.1
+make prerequisites
 ```
 
 ## Setup

docs/management/init.md

@@ -2,11 +2,9 @@
 
 ## Prerequisites
 
-Install [copier](https://copier.readthedocs.io/) for template operations. It is recommended to install via [pipx](https://pipx.pypa.io/) with the following command:
-
-```{note}
-Find pipx installation instruction [here](https://pipx.pypa.io/stable/installation/).
-```
+[pipx](https://pipx.pypa.io/) is required to manage the standalone tools used across the development lifecycle.
+Please refer to pipx's installation instructions [here](https://pipx.pypa.io/stable/installation/).
+Once pipx is set up, install the copier for project generation using the following command:
 
 ```bash
 pipx install copier==9.2.0

includes/sample.jinja

@@ -33,15 +33,12 @@ If you find this helpful, please consider [sponsorship](https://github.com/spons
 
 ## 🔧 Prerequisites
 
-Certain system-level Python applications are needed and it is recommended to use [pipx](https://pypa.github.io/pipx/) to install and run them in isolated environments. Refer to pipx's installation instructions [here](https://pypa.github.io/pipx/installation/). Once `pipx` is set up, install the necessary tools using the following commands.
+[pipx](https://pipx.pypa.io/) is required to manage the standalone tools used across the development lifecycle.
+Please refer to pipx's installation instructions [here](https://pipx.pypa.io/stable/installation/).
+Once pipx is set up, install the copier for project generation using the following command:
 
 ```bash
-# Copier: Template rendering for projects.
 pipx install copier==9.2.0
-# PDM: A modern Python package and dependency manager supporting the latest PEP standards.
-pipx install pdm==2.16.1
-# Pre-commit: Automates Git hooks for code quality checks.
-pipx install pre-commit==3.7.1
 ```
 
 ## 🚀 Quickstart
@@ -52,26 +49,32 @@ pipx install pre-commit==3.7.1
    copier copy gh:serious-scaffold/ss-python /path/to/project
    ```
 
-2. Navigate to the project directory and initialize a git repository.
+1. Navigate to the project directory and initialize a git repository.
 
    ```bash
    cd /path/to/project
    git init
    ```
 
-3. Set up the development environment.
+1. Install standalone tools.
+
+   ```bash
+   make prerequisites
+   ```
+
+1. Set up the development environment.
 
    ```bash
    make dev
    ```
 
-4. Commit the initialized project.
+1. Commit the initialized project.
 
    ```bash
    git add .
    git commit -m "Initialize from serious-scaffold."
    ```
 
-5. That's it! Feel free to focus on the coding within `src` folder.
+1. That's it! Feel free to focus on the coding within `src` folder.
 
 [%- endmacro %]

template/.devcontainer/Dockerfile.jinja

@@ -17,6 +17,11 @@ ENV PYTHONDONTWRITEBYTECODE=1
 ENV PYTHONHASHSEED=0
 ENV PYTHONUNBUFFERED=1
 
+# Config pipx
+ENV PIPX_HOME=/usr/local/pipx
+ENV PIPX_BIN_DIR=/usr/local/bin
+ENV PIPX_DEFAULT_PYTHON=/usr/local/bin/python
+
 # renovate: depName=debian_12/bash-completion
 ARG BASH_COMPLETION_VERSION="1:2.11-6"
 # renovate: depName=debian_12/pipx
@@ -26,27 +31,17 @@ ARG SUDO_VERSION="1.9.13p3-1+deb12u1"
 # renovate: depName=debian_12/vim
 ARG VIM_VERSION="2:9.0.1378-2"
 
+# Install system dependencies and override pipx with a newer version
 RUN apt-get update && apt-get install -y --no-install-recommends \
     bash-completion="${BASH_COMPLETION_VERSION}" \
     pipx="${PIPX_VERSION}" \
     sudo="${SUDO_VERSION}" \
     vim="${VIM_VERSION}" \
-    && apt-get clean -y && rm -rf /var/lib/apt/lists/*
-
-# Config pipx
-ENV PIPX_HOME=/usr/local/pipx
-ENV PIPX_BIN_DIR=/usr/local/bin
-ENV PIPX_DEFAULT_PYTHON=/usr/local/bin/python
-
-# Install pdm
-RUN pipx install pdm==2.16.1
-
-# Install pre-commit
-RUN if [ "${PYTHON_VERSION}" = "3.8" ]; then \
-        pipx install pre-commit==3.5.0; \
-    else \
-        pipx install pre-commit==3.7.1; \
-    fi
+    && pipx install pipx==1.6.0 \
+    && apt-get purge -y --autoremove pipx \
+    && apt-get clean -y \
+    && rm -rf /var/lib/apt/lists/* \
+    && hash -r
 
 # Install prerequisites
 RUN --mount=source=Makefile,target=Makefile \

template/.renovaterc.json.jinja

@@ -32,7 +32,7 @@
             ],
             "matchStrings": [
                 "pip install.* (?<depName>.*?)==(?<currentValue>.*?)[\"\n]",
-                "pipx install (?<depName>.*?)==(?<currentValue>.*?)[;\n]"
+                "pipx install( --force)? (?<depName>.*?)==(?<currentValue>.*?)\n"
             ]
         },
         {

template/Makefile.jinja

@@ -9,6 +9,9 @@
 # Documentation target directory, will be adapted to specific folder for readthedocs.
 PUBLIC_DIR := $(shell [ "$$READTHEDOCS" = "True" ] && echo "$${READTHEDOCS_OUTPUT}html" || echo "public")
 
+# Determine the Python version used by pipx.
+PIPX_PYTHON_VERSION := $(shell `pipx environment --value PIPX_DEFAULT_PYTHON` -c "from sys import version_info; print(f'{version_info.major}.{version_info.minor}')")
+
 ########################################################################################
 # Development Environment Management
 ########################################################################################
@@ -55,6 +58,12 @@ dev:
 
 # Install standalone tools
 prerequisites:
+	pipx install --force pdm==2.16.1
+ifeq ($(PIPX_PYTHON_VERSION), 3.8)
+	pipx install --force pre-commit==3.5.0
+else
+	pipx install --force pre-commit==3.7.1
+endif
 	pipx install --force pyproject-fmt==2.1.4
 	pipx install --force ruff==0.5.0
 

template/docs/development/setup-dev-env.md

@@ -4,17 +4,12 @@ This page shows the approach to set up development environment. To simplify the
 
 ## Prerequisites
 
-Several necessary tools need to be installed with the following commands:
-
-```{note}
-Using `pipx` for management is recommended and you can find pipx's installation instructions [here](https://pypa.github.io/pipx/installation/).
-```
+[pipx](https://pipx.pypa.io/) is required to manage the standalone tools used across the development lifecycle.
+Please refer to pipx's installation instructions [here](https://pipx.pypa.io/stable/installation/).
+Once pipx is set up, install the needed standalone tools with the following command:
 
 ```bash
-# PDM: A modern Python package and dependency manager supporting the latest PEP standards.
-pipx install pdm==2.16.1
-# Pre-commit: Automates Git hooks for code quality checks.
-pipx install pre-commit==3.7.1
+make prerequisites
 ```
 
 ## Setup

template/docs/management/init.md.jinja

@@ -3,11 +3,9 @@
 
 ## Prerequisites
 
-Install [copier](https://copier.readthedocs.io/) for template operations. It is recommended to install via [pipx](https://pipx.pypa.io/) with the following command:
-
-```{note}
-Find pipx installation instruction [here](https://pipx.pypa.io/stable/installation/).
-```
+[pipx](https://pipx.pypa.io/) is required to manage the standalone tools used across the development lifecycle.
+Please refer to pipx's installation instructions [here](https://pipx.pypa.io/stable/installation/).
+Once pipx is set up, install the copier for project generation using the following command:
 
 ```bash
 pipx install copier==9.2.0