chore: add CI and community hygiene

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,6 +1,11 @@
 ## Description
 
-<!-- Brief description of changes -->
+<!-- What does this PR do? -->
+
+## Related Issue
+
+<!-- Link to the issue this PR addresses -->
+Fixes #
 
 ## Type of Change
 
@@ -11,11 +16,17 @@
 
 ## Checklist
 
+- [ ] I have read the [CONTRIBUTING](../CONTRIBUTING.md) guide
 - [ ] Tests pass locally (`make test-python`)
 - [ ] Linting passes (`make verify`)
 - [ ] Documentation updated (if applicable)
-- [ ] Commit messages follow conventional format
+- [ ] My commits are signed off (`git commit -s`)
+
+## Testing
 
-## Related Issues
+<!-- How was this tested? -->
 
-<!-- Link related issues: Fixes #123 -->
+```bash
+make verify
+make test-python
+```

.github/workflows/check-pr-title.yaml

@@ -1,15 +1,28 @@
 name: Check PR Title
 
 on:
-  pull_request:
-    types: [opened, edited, synchronize]
+  pull_request_target:
+    branches:
+      - main
+    types:
+      - edited
+      - opened
+      - reopened
+      - synchronize
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  pull-requests: read
 
 jobs:
   check:
+    name: Check PR Title
     runs-on: ubuntu-latest
     steps:
-      - name: Check conventional commit format
-        uses: amannn/action-semantic-pull-request@v5
+      - uses: amannn/action-semantic-pull-request@v6.1.1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
@@ -18,8 +31,23 @@ jobs:
             fix
             revert
             chore
+          scopes: |
+            ci
+            docs
+            deps
+            agents
+            core
+            trainer
+            optimizer
+            hub
+            examples
+            benchmarks
           requireScope: false
+          ignoreLabels: |
+            do-not-merge/work-in-progress
+            dependencies
+            area/release
           subjectPattern: ^[a-z].+$
           subjectPatternError: |
-            PR title must start with lowercase letter.
+            PR title must start with a lowercase letter.
             Example: "feat: add training job tool"

.github/workflows/docs.yaml

@@ -0,0 +1,69 @@
+name: Documentation
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "kubeflow_mcp/**"
+      - ".readthedocs.yaml"
+      - ".github/workflows/docs.yaml"
+      - "pyproject.toml"
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "kubeflow_mcp/**"
+      - ".readthedocs.yaml"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    name: Build Documentation
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build documentation
+        run: |
+          uv sync --extra docs
+          uv run sphinx-build -b html docs/source docs/_build/html
+
+      - name: Upload documentation artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: documentation
+          path: docs/_build/html
+          retention-days: 7
+
+  linkcheck:
+    runs-on: ubuntu-latest
+    name: Check Links
+    continue-on-error: true
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Check links
+        run: |
+          uv sync --extra docs
+          uv run sphinx-build -b linkcheck docs/source docs/_build/linkcheck || true

.github/workflows/publish.yaml

@@ -0,0 +1,80 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      test_pypi:
+        description: 'Publish to Test PyPI instead'
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run tests
+        run: make test-python
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-test-pypi:
+    needs: build
+    if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.test_pypi == 'true' }}
+    runs-on: ubuntu-latest
+    environment:
+      name: test-pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to Test PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: build
+    if: ${{ github.event_name == 'release' }}
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+

.github/workflows/welcome-new-contributors.yaml

@@ -0,0 +1,54 @@
+name: Welcome new contributors
+
+on:
+  pull_request_target:
+    types:
+      - opened
+  issues:
+    types:
+      - opened
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  welcome:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/first-interaction@v3
+        with:
+          repo_token: ${{ secrets.GITHUB_TOKEN }}
+          issue_message: |
+            🎉 **Welcome to the Kubeflow MCP Server!** 🎉
+
+            Thanks for opening your first issue! We're happy to have you as part of our community 🚀
+
+            **Here's what happens next:**
+
+            - Our team will review your issue soon!
+            - If you'd like to contribute to this issue, check out our [Contributing Guide](https://github.com/kubeflow/mcp-server/blob/main/CONTRIBUTING.md)
+
+            **Join the community:**
+            - **Slack**: Join [#kubeflow-ml-experience](https://www.kubeflow.org/docs/about/community/#slack-channels) on CNCF Slack
+            - **Meetings**: Attend the [Training WG](https://bit.ly/2PWVCkV) bi-weekly meetings
+
+            Feel free to ask questions in the comments if you need any help!
+            Thanks again for contributing to Kubeflow! 🙏
+
+          pr_message: |
+            🎉 **Welcome to the Kubeflow MCP Server!** 🎉
+
+            Thanks for opening your first PR! We're happy to have you as part of our community 🚀
+
+            **Here's what happens next:**
+
+            - Please check out our [Contributing Guide](https://github.com/kubeflow/mcp-server/blob/main/CONTRIBUTING.md) if you haven't already
+            - Our team will review your PR soon!
+
+            **Join the community:**
+            - **Slack**: Join [#kubeflow-ml-experience](https://www.kubeflow.org/docs/about/community/#slack-channels) on CNCF Slack
+            - **Meetings**: Attend the [Training WG](https://bit.ly/2PWVCkV) bi-weekly meetings
+
+            Feel free to ask questions in the comments if you need any help!
+            Thanks again for contributing to Kubeflow! 🙏

.gitignore

@@ -41,6 +41,9 @@ __debug_bin
 # Testing
 .pytest_cache/
 .coverage
+.coverage.*
+coverage.xml
+coverage.json
 htmlcov/
 .tox/
 .nox/
@@ -70,6 +73,3 @@ benchmark-results.json
 
 # Docs build output
 docs/_build/
-
-# Test artifacts
-coverage.json

Makefile

@@ -1,31 +1,70 @@
+# Copyright The Kubeflow Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 SHELL = /usr/bin/env bash -o pipefail
 .SHELLFLAGS = -ec
 
+.PHONY: help uv install-dev verify format test-python test test-cov clean
+
 PROJECT_DIR := $(shell dirname $(abspath $(lastword $(MAKEFILE_LIST))))
 
 help: ## Display this help.
-	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
+
+##@ Setup
 
-.PHONY: uv
-uv: ## Install UV
+uv: ## Install uv
 	@command -v uv &> /dev/null || { \
 	  curl -LsSf https://astral.sh/uv/install.sh | sh; \
-	  echo "✅ uv has been installed."; \
+	  echo "uv has been installed."; \
 	}
 
-.PHONY: verify
-verify: ## Run linting, formatting and type checking
+install-dev: uv ## Install all development dependencies
+	@uv sync --all-extras
+	@uv run pre-commit install
+
+##@ Quality
+
+verify: ## Run linting and formatting checks
 	@uv lock --check
 	@uv run ruff check .
 	@uv run ruff format --check .
 
-.PHONY: test-python
-test-python: ## Run Python unit tests
+format: ## Auto-format and fix lint issues
+	@uv run ruff check --fix .
+	@uv run ruff format .
+
+##@ Testing
+
+test-python: ## Run unit tests
 	@uv sync --all-extras
 	@uv run pytest --cov=kubeflow_mcp --cov-report=$(or $(report),term)
 
-.PHONY: install-dev
-install-dev: uv ## Install dependencies and tools
-	@echo "Syncing dependencies with uv..."
+test: ## Run all tests (unit + integration)
+	@uv sync --all-extras
+	@uv run pytest tests/ kubeflow_mcp/ -v --tb=short
+
+test-cov: ## Run tests with HTML coverage report
 	@uv sync --all-extras
-	@echo "Environment is ready."
+	@uv run pytest --cov=kubeflow_mcp --cov-report=term-missing --cov-report=html
+	@echo "Coverage report: htmlcov/index.html"
+
+##@ Cleanup
+
+clean: ## Remove all build and cache artifacts
+	rm -rf .pytest_cache .ruff_cache .coverage htmlcov
+	rm -rf dist build *.egg-info
+	find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete 2>/dev/null || true
+	@echo "Cleaned build artifacts"