Chore/update docs and release process

.github/workflows/build-python.yaml

@@ -39,15 +39,5 @@ jobs:
         with:
           name: python-wheel
           path: dist/*.whl
+          overwrite: true
 
-  integration-test:
-    strategy:
-      fail-fast: true
-      matrix:
-        python3_version: ["3.10", "3.11", "3.12", "3.13"]
-        # python3_version: ["3.13"]
-    needs: build
-    uses: ./.github/workflows/platform-integration-test.yaml
-    with:
-      wheel: ${{ needs.build.outputs.wheel }}
-      python_version: ${{ matrix.python3_version }}

.github/workflows/publish-test.yaml

@@ -1,10 +1,12 @@
 name: TestPyPIBuild
 
 on:
-  push:
-    branches:
-      - develop
-      - chore/rewrite-in-python
+  # push:
+  #   branches:
+  #     - develop
+  #     - chore/update-docs-and-release-process
+  # repository_dispatch:
+  #   types: [alpha-release-created, stable-release-created]
   workflow_dispatch:
 
 jobs:
@@ -41,8 +43,8 @@ jobs:
       id-token: write
     needs: [build]
     runs-on: ubuntu-22.04
-    # If branch is 'develop'
-    if: github.ref == 'refs/heads/develop'
+    # If branch is 'develop' or triggered by repository dispatch
+    if: github.ref == 'refs/heads/develop' || github.ref == 'refs/heads/chore/update-docs-and-release-process'  || github.event_name == 'repository_dispatch'
 
     steps:
         - uses: actions/checkout@v4

.github/workflows/publish.yaml

@@ -1,9 +1,10 @@
 name: PyPIBuild
 
 on:
-  push:
-    branches:
-      - main
+  release:
+    types: [published]
+  repository_dispatch:
+    types: [alpha-release-created, stable-release-created]
   workflow_dispatch:
 
 jobs:
@@ -106,8 +107,8 @@ jobs:
       id-token: write
     needs: [build_macos, build_linux_x86_64, build_linux_arm]
     runs-on: ubuntu-22.04
-    # If branch is 'main'
-    if: github.ref == 'refs/heads/main'
+    # If branch is 'main' or triggered by repository dispatch
+    if: github.ref == 'refs/heads/main' || github.event_name == 'repository_dispatch' || github.event_name == 'release'
 
     steps:
         - uses: actions/checkout@v4

.github/workflows/release-please.yaml

@@ -0,0 +1,72 @@
+name: Release Please
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+      - chore/update-docs-and-release-process
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  # Run full test suite before any release operations
+  test-suite:
+    uses: ./.github/workflows/test-suite.yaml
+
+  release-please:
+    runs-on: ubuntu-latest
+    needs: test-suite
+    if: needs.test-suite.outputs.tests_passed == 'true'
+    outputs:
+      releases_created: ${{ steps.release.outputs.releases_created }}
+      paths_released: ${{ steps.release.outputs.paths_released }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          config-file: .release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  # Trigger appropriate publish workflows based on release type
+  trigger-publish:
+    needs: release-please
+    if: ${{ needs.release-please.outputs.releases_created }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check if alpha release
+        id: check_alpha
+        run: |
+          # Get the version from the main package
+          VERSION=$(cat .release-please-manifest.json | jq -r '."."')
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          if [[ "$VERSION" =~ [0-9]+\.[0-9]+\.[0-9]+a[0-9]+ ]]; then
+            echo "is_alpha=true" >> $GITHUB_OUTPUT
+            echo "Alpha version detected: $VERSION"
+          else
+            echo "is_alpha=false" >> $GITHUB_OUTPUT
+            echo "Stable version detected: $VERSION"
+          fi
+
+      # For develop branch: trigger TestPyPI build (both alpha and stable releases go to TestPyPI from develop)
+      - name: Trigger TestPyPI Build (Develop)
+        if: github.ref == 'refs/heads/develop' || github.ref == 'refs/heads/chore/update-docs-and-release-process'
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          event-type: ${{ steps.check_alpha.outputs.is_alpha == 'true' && 'alpha-release-created' || 'stable-release-created' }}
+          client-payload: '{"version": "${{ steps.check_alpha.outputs.version }}", "releases": "${{ needs.release-please.outputs.paths_released }}"}'
+
+      # For main branch: trigger PyPI build (both alpha and stable releases go to PyPI from main)
+      - name: Trigger PyPI Build (Main)
+        if: github.ref == 'refs/heads/main'
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          event-type: ${{ steps.check_alpha.outputs.is_alpha == 'true' && 'alpha-release-created' || 'stable-release-created' }}
+          client-payload: '{"version": "${{ steps.check_alpha.outputs.version }}", "releases": "${{ needs.release-please.outputs.paths_released }}"}'

.github/workflows/test-suite.yaml

@@ -0,0 +1,121 @@
+name: Test Suite
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+  workflow_call:
+    outputs:
+      tests_passed:
+        description: "Whether all tests passed"
+        value: ${{ jobs.report.outputs.success }}
+  workflow_dispatch:
+
+jobs:
+  # Step 1: Fast lint and format checks (fail fast on code style)
+  lint-check:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Run linting (fail fast)
+        run: |
+          uv sync --frozen
+          uv run ruff check
+          uv run ruff format --check
+
+  # Step 2: Build (only after linting passes)
+  build:
+    runs-on: ubuntu-22.04
+    needs: lint-check
+    outputs:
+      wheel: ${{ steps.find_wheel.outputs.wheel_path }}
+    steps:
+      - name: Checkout this repo
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Build otdf-python wheel using uv
+        run: |
+          uv sync --frozen
+          uv build
+        shell: bash
+
+      - name: Find built wheel
+        id: find_wheel
+        run: |
+          wheel_path=$(ls dist/*.whl | head -n1)
+          echo "wheel_path=$wheel_path" >> $GITHUB_OUTPUT
+        shell: bash
+
+      - name: Upload wheel as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-wheel
+          path: dist/*.whl
+
+  # Step 3: Unit tests (only after build succeeds)
+  unit-tests:
+    runs-on: ubuntu-22.04
+    needs: build
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Run unit tests
+        run: |
+          uv sync --frozen
+          uv run pytest -m "not integration" --tb=short -v tests/
+
+  # Step 4: Integration tests (only after unit tests pass)
+  integration-tests:
+    strategy:
+      fail-fast: true
+      matrix:
+        python3_version: ["3.10", "3.11", "3.12", "3.13"]
+    needs: [build, unit-tests]
+    uses: ./.github/workflows/platform-integration-test.yaml
+    with:
+      wheel: ${{ needs.build.outputs.wheel }}
+      python_version: ${{ matrix.python3_version }}
+
+  report:
+    runs-on: ubuntu-22.04
+    needs: [lint-check, build, unit-tests, integration-tests]
+    if: always()
+    outputs:
+      success: ${{ steps.check.outputs.success }}
+    steps:
+      - name: Check all jobs succeeded
+        id: check
+        run: |
+          if [[ "${{ needs.lint-check.result }}" == "success" && "${{ needs.build.result }}" == "success" && "${{ needs.unit-tests.result }}" == "success" && "${{ needs.integration-tests.result }}" == "success" ]]; then
+            echo "success=true" >> $GITHUB_OUTPUT
+            echo "✅ All tests passed!"
+          else
+            echo "success=false" >> $GITHUB_OUTPUT
+            echo "❌ Some tests failed:"
+            echo "  Lint Check: ${{ needs.lint-check.result }}"
+            echo "  Build: ${{ needs.build.result }}"
+            echo "  Unit Tests: ${{ needs.unit-tests.result }}"
+            echo "  Integration Tests: ${{ needs.integration-tests.result }}"
+            exit 1
+          fi

.pre-commit-config.yaml

@@ -1,4 +1,8 @@
 ---
+default_install_hook_types:
+  - pre-commit
+  - commit-msg
+  - post-rewrite
 exclude: |
   (?x)^(
     otdf_python/.*
@@ -17,26 +21,6 @@ repos:
           - id: check-yaml
           - id: end-of-file-fixer
           - id: trailing-whitespace
-
-    # - repo: https://github.com/tekwizely/pre-commit-golang
-    #   rev: master
-    #   hooks:
-    #       - id: go-lint
-
-    - repo: https://github.com/dnephin/pre-commit-golang
-      rev: v0.5.1
-      hooks:
-          - id: go-fmt
-
-          - id: go-vet
-          # - id: golangci-lint
-            # timeout is needed for CI
-            # args: [-E, gosec, -E, goconst, -E, govet, --timeout, 300s]
-          # - id: go-imports
-          # - id: go-cyclo
-          #   args: [-over=15]
-          # - id: validate-toml
-          - id: no-go-testing
     - repo: https://github.com/codespell-project/codespell
       rev: v2.4.1
       hooks:
@@ -45,9 +29,15 @@ repos:
 
     - repo: https://github.com/astral-sh/ruff-pre-commit
       # Ruff version.
-      rev: v0.12.10
+      rev: v0.12.12
       hooks:
         # Run the linter.
         - id: ruff
         # Run the formatter.
         - id: ruff-format
+    - repo: https://github.com/compilerla/conventional-pre-commit
+      rev: v4.2.0
+      hooks:
+        - id: conventional-pre-commit
+          stages: [commit-msg,post-rewrite]
+          args: [--verbose,--scopes=feat,fix,docs,style,test,chore,ci]

.release-please-config.json

@@ -0,0 +1,31 @@
+{
+  "release-type": "python",
+  "include-v-in-tag": true,
+  "packages": {
+    ".": {
+      "release-type": "python",
+      "package-name": "otdf-python",
+      "extra-files": [
+        "src/otdf_python/cli.py",
+        "tests/test_cli.py"
+      ]
+    },
+    "otdf-python-proto": {
+      "release-type": "python",
+      "package-name": "otdf-python-proto"
+    }
+  },
+  "changelog-sections": [
+    { "type": "feat", "section": "Features", "hidden": false },
+    { "type": "fix", "section": "Bug Fixes", "hidden": false },
+    { "type": "perf", "section": "Performance Improvements", "hidden": false },
+    { "type": "revert", "section": "Reverts", "hidden": false },
+    { "type": "docs", "section": "Documentation", "hidden": false },
+    { "type": "style", "section": "Styles", "hidden": true },
+    { "type": "chore", "section": "Miscellaneous Chores", "hidden": true },
+    { "type": "refactor", "section": "Code Refactoring", "hidden": false },
+    { "type": "test", "section": "Tests", "hidden": true },
+    { "type": "build", "section": "Build System", "hidden": false },
+    { "type": "ci", "section": "Continuous Integration", "hidden": true }
+  ]
+}

.release-please-manifest.json

@@ -0,0 +1,4 @@
+{
+    ".": "0.3.0a8",
+    "otdf-python-proto": "0.3.0a8"
+}

PROTOBUF_SETUP.md

@@ -86,7 +86,7 @@ curl -o proto-gen/proto-files/kas.proto https://raw.githubusercontent.com/opentd
 
 ## Dependencies
 
-The proto-gen sub-module includes these dependencies:
+The otdf-python-proto sub-module includes these dependencies:
 - `grpcio>=1.74.0` - gRPC runtime
 - `grpcio-tools>=1.74.0` - Protocol buffer compiler
 - `protobuf>=6.31.1` - Protocol buffer runtime
@@ -128,7 +128,7 @@ The generated Python files include:
 - **`kas_pb2.py`** - Protocol buffer message classes
 - **`kas_pb2_grpc.py`** - gRPC service client and server classes
 
-These files are automatically synced to `src/otdf_python/proto/` in the main project.
+These files are automatically synced to `otdf-python-proto/generated/` and used by the main project in `src/otdf_python/`.
 
 ## Fallback Strategy