Merge 'dev' to 'main'

.github/CONTRIBUTING.md

@@ -27,8 +27,8 @@ You can contribute by:
 Start by opening an issue to describe your proposed change or the problem you
 encountered. This helps maintainers review and guide the work before coding begins.
 
-> For minor changes, such as typo fixes, you may skip this step and submit a pull
-> request directly.
+> For minor changes, such as typo fixes, you may skip this step and submit a pull request
+> directly.
 
 ### Step 2: Make Your Changes
 
@@ -75,7 +75,7 @@ To set up locally:
 3. Clone the repository and run:
 
 ```bash
-make install
+make setup
 ```
 
 > If using `uv`, a compatible virtual environment will be created automatically.

.github/actions/build-mkdocs/action.yml

@@ -18,30 +18,17 @@ runs:
     - name: Setup gh-pages Branch
       shell: bash
       run: |
-        # Store current branch
-        CURRENT_BRANCH=$(git branch --show-current)
-
-        # Check if gh-pages branch exists
-        if git ls-remote --heads origin gh-pages | grep -q gh-pages; then
-          echo "gh-pages branch exists, fetching..."
-          git fetch origin gh-pages:gh-pages
-        else
-          echo "gh-pages branch doesn't exist, creating..."
+        if ! git ls-remote --heads origin gh-pages | grep -q gh-pages; then
+          CURRENT_BRANCH=$(git branch --show-current)
           git checkout --orphan gh-pages
           git reset --hard
           git commit --allow-empty -m "Initial gh-pages commit"
           git push origin gh-pages
           git checkout "$CURRENT_BRANCH"
         fi
 
-    - name: Build and Deploy Docs with Mike
+    - name: Build and Deploy Docs
       shell: bash
       run: |
-        echo "Deploying Docs Version: ${{ inputs.docs-version }}"
         uv run mike deploy --push --update-aliases "${{ inputs.docs-version }}" latest
-
-    - name: Set Default Version to Docs
-      shell: bash
-      run: |
-        echo "Setting 'Latest' as Default Version"
         uv run mike set-default --push latest

.github/actions/create-release/action.yml

@@ -26,52 +26,24 @@ runs:
       run: |
         if gh release view "${{ inputs.version }}" >/dev/null 2>&1; then
           echo "exists=true" >> $GITHUB_OUTPUT
-          echo "Release ${{ inputs.version }} already exists"
         else
           echo "exists=false" >> $GITHUB_OUTPUT
-          echo "Release ${{ inputs.version }} doesn't exist"
         fi
       env:
         GH_TOKEN: ${{ inputs.token }}
 
-    - name: Generate Release Notes
+    - name: Create Release
       if: steps.check_release.outputs.exists == 'false'
       shell: bash
       run: |
-        echo "Generating release notes..."
         LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+        RANGE="${LAST_TAG:+$LAST_TAG..HEAD}"
+        COMMITS=$(git log ${RANGE:---max-count=10} --pretty=format:"- %s" --no-merges)
 
-        if [ -z "$LAST_TAG" ]; then
-          echo "No previous tags found, using last 10 commits..."
-          COMMITS=$(git log --pretty=format:"- %s" --no-merges -10)
-        else
-          echo "Previous tag found: $LAST_TAG"
-          COMMITS=$(git log "${LAST_TAG}..HEAD" --pretty=format:"- %s" --no-merges)
-        fi
-
-        cat > release-notes.md << EOF
-        ## Changes
-
-        $COMMITS
-        EOF
-
-        echo "Release notes generated:"
-        cat release-notes.md
-
-    - name: Create Release
-      if: steps.check_release.outputs.exists == 'false'
-      shell: bash
-      run: |
-        echo "Creating release ${{ inputs.version }}..."
         gh release create "${{ inputs.version }}" \
           --title "${{ inputs.version }}" \
-          --notes-file release-notes.md
-        echo "Release ${{ inputs.version }} created successfully"
+          --notes "## Changes
+
+        $COMMITS"
       env:
         GH_TOKEN: ${{ inputs.token }}
-
-    - name: Skip Release
-      if: steps.check_release.outputs.exists == 'true'
-      shell: bash
-      run: |
-        echo "Skipping release creation - ${{ inputs.version }} already exists"

.github/actions/setup-python-env/action.yml

@@ -25,39 +25,20 @@ runs:
         enable-cache: true
 
     - name: Install dependencies with uv
-      id: install-deps
       shell: bash
       run: |
-        # Check if we should install all extras
-        if [ -z "${{ inputs.uv-group }}" ] && [ -z "${{ inputs.uv-extra }}" ]; then
-          echo "Installing all extras (default when no group or extra specified)..."
-          uv sync --all-extras
-        elif [ "${{ inputs.uv-extra }}" = "--all-extras" ]; then
-          echo "Installing all extras (explicitly requested)..."
-          if [ -n "${{ inputs.uv-group }}" ]; then
-            echo "Note: Installing all extras overrides the specified group: ${{ inputs.uv-group }}"
-          fi
-          uv sync --all-extras
+        ARGS=""
+        if [ "${{ inputs.uv-extra }}" = "--all-extras" ] || [ -z "${{ inputs.uv-group }}${{ inputs.uv-extra }}" ]; then
+          ARGS="--all-extras"
         else
-          echo "Installing with group: ${{ inputs.uv-group }}, and extra: ${{ inputs.uv-extra }}..."
-          if [ -n "${{ inputs.uv-group }}" ] && [ -n "${{ inputs.uv-extra }}" ]; then
-            uv sync --group ${{ inputs.uv-group }} --extra ${{ inputs.uv-extra }}
-          elif [ -n "${{ inputs.uv-group }}" ]; then
-            uv sync --group ${{ inputs.uv-group }}
-          elif [ -n "${{ inputs.uv-extra }}" ]; then
-            uv sync --extra ${{ inputs.uv-extra }}
-          else
-            uv sync
-          fi
+          [ -n "${{ inputs.uv-group }}" ] && ARGS="$ARGS --group ${{ inputs.uv-group }}"
+          [ -n "${{ inputs.uv-extra }}" ] && ARGS="$ARGS --extra ${{ inputs.uv-extra }}"
         fi
+        uv sync $ARGS
 
     - name: Verify uv and environment
-      id: verify
       shell: bash
       run: |
-        echo "uv version:"
         uv --version
-        echo "Virtual environments:"
         uv venv list
-        echo "Python version:"
         uv run python --version

.github/actions/test-code/action.yml

@@ -0,0 +1,23 @@
+name: Test Code
+description: Run Python tests with Pytest
+
+inputs:
+  src-project-folder:
+    description: "Directory where the project is located"
+    required: true
+    default: "src"
+
+  src-tests-folder:
+    description: "Directory where the tests are located"
+    required: true
+    default: "tests"
+
+runs:
+  using: composite
+  steps:
+    - name: Run tests with Pytest
+      shell: bash
+      run: |
+        if [ -d "${{ inputs.src-tests-folder }}" ] && [ -n "$(find ${{ inputs.src-tests-folder }} -name 'test_*.py')" ]; then
+          uv run pytest ${{ inputs.src-tests-folder }}
+        fi

.github/workflows/workflow.yml

@@ -8,10 +8,11 @@ on:
 
 env:
   SRC_PYTHON_VERSION: "3.11"
+  TEST_PATH: "tests"
 
 jobs:
-  setup:
-    name: Setup Code
+  setup-test:
+    name: Setup and Test
     runs-on: ubuntu-latest
 
     steps:
@@ -25,11 +26,16 @@ jobs:
           uv-group: "pipeline"
           uv-extra: "--all-extras"
 
+      - name: Run Tests
+        uses: ./.github/actions/test-code
+        with:
+          src-tests-folder: ${{ env.TEST_PATH }}
+
   build-deploy-docs:
     if: github.ref == 'refs/heads/main'
     name: Build MkDocs Documentation
     runs-on: ubuntu-latest
-    needs: setup
+    needs: setup-test
 
     permissions:
       contents: write

AGENTS.md

@@ -9,9 +9,9 @@ many optional settings and Jinja2 template blocks.
 
 Before interacting with the template, make sure to:
 
-1. **Review the README**: The `README.md` provides a high-level overview of the
-   template, its features, CI/CD workflow, and instructions to generate new projects.
-   Key features include:
+1. **Review the README**: The `README.md` provides a high-level overview of the template,
+   its features, CI/CD workflow, and instructions to generate new projects. Key features
+   include:
 
    - Linting & type checking (Ruff & Mypy)
    - Security scanning (Bandit)
@@ -36,7 +36,7 @@ Before interacting with the template, make sure to:
   - Create new projects inside the `workspaces/` directory.
   - Run the Makefile targets to validate functionality:
 
-    - `make install` → installs dependencies
+    - `make setup` → installs dependencies
     - `make pipeline` → runs linting, type checking, security analysis, complexity
       checks, and tests
     - `make all` → full workflow including documentation preview