Beta preparations

.github/workflows/docs.yaml

@@ -0,0 +1,56 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version label (defaults to 'dev')"
+        required: false
+        default: "dev"
+
+permissions:
+  contents: write
+
+concurrency:
+  group: docs-deploy
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v3
+        with:
+          python-version: "3.13"
+      - name: Install docs dependencies
+        run: uv lock --python 3.13 && uv sync --group docs
+      - name: Build docs (strict)
+        run: uv run --group docs mkdocs build --strict
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      - name: Deploy (main → dev)
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: uv run --group docs mike deploy --push --update-aliases dev
+      - name: Deploy (tag → versioned)
+        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+        run: |
+          VERSION="${GITHUB_REF#refs/tags/v}"
+          uv run --group docs mike deploy --push "$VERSION"
+          # NOTE: promotion to the `latest` alias and `mike set-default` is
+          # deliberately manual. Auto-promoting on every `v*` tag would demote
+          # a parallel-line release (e.g., a v1.x patch tag pushed after v2.x
+          # would silently make v1 the default). Promote via workflow_dispatch
+          # only after confirming the new tag is the project's newest line.
+      - name: Deploy (workflow_dispatch)
+        if: github.event_name == 'workflow_dispatch'
+        env:
+          VERSION_LABEL: ${{ github.event.inputs.version }}
+        run: uv run --group docs mike deploy --push --update-aliases "$VERSION_LABEL"

.github/workflows/lint.yaml

@@ -45,3 +45,20 @@ jobs:
             uv run python -m scripts.codegen verify "$pkg"
             echo "::endgroup::"
           done
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          python-version: "3.13"
+      - name: Install docs dependencies
+        run: uv lock --python 3.13 && uv sync --group docs
+      - name: Build docs (strict)
+        run: uv run --group docs mkdocs build --strict
+      - name: Check links
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: --config lychee.toml docs/
+          fail: true
+          github-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/publish-test.yaml

@@ -33,6 +33,7 @@ jobs:
     outputs:
       dev-version: ${{ steps.version.outputs.dev-version }}
       core-dev-version: ${{ steps.version.outputs.core-dev-version }}
+      k8s-versions: ${{ steps.version.outputs.k8s-versions }}
     steps:
       - uses: actions/checkout@v4
       - uses: astral-sh/setup-uv@v3
@@ -65,12 +66,23 @@ jobs:
           CORE_DEV_VERSION=$(python3 -c "from packaging.version import Version; print(Version('${CORE_DEV_VERSION_RAW}'))")
           echo "core-dev-version=${CORE_DEV_VERSION}" >> "$GITHUB_OUTPUT"
           sed -i "s/\"kubex-core\"/\"kubex-core==${CORE_DEV_VERSION}\"/" pyproject.toml
+          K8S_VERSIONS_JSON='{'
+          FIRST=true
           for pkg in packages/kubex-k8s-*/; do
             K8S_DEV_VERSION="$(sed -n 's/^version = "\(.*\)"/\1/p' "${pkg}pyproject.toml")"
+            K8S_NORMALIZED=$(python3 -c "from packaging.version import Version; print(Version('${K8S_DEV_VERSION}'))")
             pkg_name=$(basename "$pkg")
-            sed -i "s/\"${pkg_name}\"/\"${pkg_name}==${K8S_DEV_VERSION}\"/" pyproject.toml
+            sed -i "s/\"${pkg_name}\"/\"${pkg_name}==${K8S_NORMALIZED}\"/" pyproject.toml
             sed -i "s/\"kubex-core\"/\"kubex-core==${CORE_DEV_VERSION}\"/" "${pkg}pyproject.toml"
+            if [ "$FIRST" = true ]; then
+              FIRST=false
+            else
+              K8S_VERSIONS_JSON="${K8S_VERSIONS_JSON},"
+            fi
+            K8S_VERSIONS_JSON="${K8S_VERSIONS_JSON}\"${pkg_name}\":\"${K8S_NORMALIZED}\""
           done
+          K8S_VERSIONS_JSON="${K8S_VERSIONS_JSON}}"
+          echo "k8s-versions=${K8S_VERSIONS_JSON}" >> "$GITHUB_OUTPUT"
 
       - name: Build packages
         run: |
@@ -102,7 +114,7 @@ jobs:
         with:
           script: |
             const sha = context.payload.pull_request.head.sha;
-            const required = ['pre-commit', 'lint', 'format', 'mypy', 'test'];
+            const required = ['pre-commit', 'lint', 'format', 'mypy', 'test', 'docs'];
             const sleep = ms => new Promise(r => setTimeout(r, ms));
 
             while (true) {
@@ -168,19 +180,16 @@ jobs:
         env:
           DEV_VERSION: ${{ needs.build.outputs.dev-version }}
           CORE_DEV_VERSION: ${{ needs.build.outputs.core-dev-version }}
+          K8S_VERSIONS: ${{ needs.build.outputs.k8s-versions }}
         with:
           script: |
             const devVersion = process.env.DEV_VERSION;
             const coreDevVersion = process.env.CORE_DEV_VERSION;
+            const k8sVersions = JSON.parse(process.env.K8S_VERSIONS);
             const packages = [
               { name: 'kubex', version: devVersion },
               { name: 'kubex-core', version: coreDevVersion },
-              { name: 'kubex-k8s-1-32', version: coreDevVersion },
-              { name: 'kubex-k8s-1-33', version: coreDevVersion },
-              { name: 'kubex-k8s-1-34', version: coreDevVersion },
-              { name: 'kubex-k8s-1-35', version: coreDevVersion },
-              { name: 'kubex-k8s-1-36', version: coreDevVersion },
-              { name: 'kubex-k8s-1-37', version: coreDevVersion },
+              ...Object.entries(k8sVersions).map(([name, version]) => ({ name, version })),
             ];
             const lines = packages.map(({ name, version }) =>
               `- [${name} ${version}](https://test.pypi.org/project/${name}/${version}/)`

.github/workflows/publish.yaml

@@ -33,35 +33,34 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Verify all package versions match the tag
+      - name: Verify kubex and kubex-core versions match the tag
         run: |
           TAG_VERSION="${GITHUB_REF_NAME#v}"
           echo "Tag version: ${TAG_VERSION}"
           ERRORS=0
 
-          # Check kubex root package (dynamic version from __version__.py)
+          # Only kubex (the umbrella) and kubex-core (the shared base models)
+          # are required to match the tag. The generated kubex-k8s-* packages
+          # are versioned independently — they track Kubernetes minor releases
+          # and do not need to be re-published on every kubex release.
           KUBEX_VERSION=$(sed -n 's/^VERSION = "\(.*\)"/\1/p' kubex/__version__.py)
           if [ "$KUBEX_VERSION" != "$TAG_VERSION" ]; then
             echo "::error::kubex version mismatch: got '${KUBEX_VERSION}', expected '${TAG_VERSION}'"
             ERRORS=$((ERRORS + 1))
           fi
 
-          # Check workspace packages (version in pyproject.toml)
-          for pkg in packages/*/; do
-            PKG_NAME=$(basename "$pkg")
-            PKG_VERSION=$(sed -n 's/^version = "\(.*\)"/\1/p' "${pkg}pyproject.toml")
-            if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
-              echo "::error::${PKG_NAME} version mismatch: got '${PKG_VERSION}', expected '${TAG_VERSION}'"
-              ERRORS=$((ERRORS + 1))
-            fi
-          done
+          KUBEX_CORE_VERSION=$(sed -n 's/^version = "\(.*\)"/\1/p' packages/kubex-core/pyproject.toml)
+          if [ "$KUBEX_CORE_VERSION" != "$TAG_VERSION" ]; then
+            echo "::error::kubex-core version mismatch: got '${KUBEX_CORE_VERSION}', expected '${TAG_VERSION}'"
+            ERRORS=$((ERRORS + 1))
+          fi
 
           if [ "$ERRORS" -gt 0 ]; then
             echo "::error::${ERRORS} package(s) have version mismatches with tag ${GITHUB_REF_NAME}"
             exit 1
           fi
 
-          echo "All package versions match tag ${GITHUB_REF_NAME}"
+          echo "kubex and kubex-core versions match tag ${GITHUB_REF_NAME}"
 
   build:
     needs: verify-versions
@@ -103,3 +102,4 @@ jobs:
       - uses: pypa/gh-action-pypi-publish@release/v1.14
         with:
           attestations: true
+          skip-existing: true

.gitignore

@@ -169,3 +169,6 @@ cython_debug/
 # Ruff
 .ruff_cache/
 scratches/
+
+
+.ralphex/