migrate-to-uv_skill

Overview

This skill migrates Keboola Python packages and Docker-based components to a modern pyproject.toml + uv build system with deterministic uv.lock dependencies and ruff-only linting. It guides detection of project type, applies a staged migration (lint baseline, metadata conversion, CI/Docker updates), and verifies builds and releases. The goal is reproducible installs, faster linting, and clean CI/CD flows.

How this skill works

The skill first auto-detects whether the repo is a PyPI package or a Keboola component using simple heuristics (setup.py, Dockerfile, CI targets) and confirms with the user if ambiguous. It then runs a phased migration: create a ruff linting baseline, convert requirements/setup metadata to pyproject.toml, generate uv.lock with uv sync, and update CI workflows or Dockerfiles to use uv commands and the uv image. Final steps include local and CI test runs, Test PyPI verification for packages, and Docker build/test/run checks for components.

When to use it

• Migrating a Python package previously using setup.py to pyproject.toml and hatchling/uv.
• Migrating a Keboola Docker component from requirements.txt to pyproject.toml with uv.lock-based installs in Docker.
• When you want deterministic dependency installs across CI, local dev and production.
• When replacing flake8 + multiple linters with ruff-only linting for speed and coverage.
• When modernizing CI workflows to use uv sync, uv build, and uv publish.

Best practices

• Detect migration type early and confirm with the repo owner before changing metadata.
• Create logical commits: lint baseline, metadata migration, CI/Docker updates—each commit should be independently reviewable.
• Use ruff exclusively; run ruff --fix and ruff format to stabilize code before metadata changes.
• For packages use >= dependency pins and relies on uv.lock for determinism; for components pin Python to major.minor via ~= matching the Docker base image.
• Generate uv.lock locally before Docker builds and commit it; update .gitignore to exclude *.egg-info/ when using dynamic versioning.

Example use cases

• Convert setup.py packages to pyproject.toml, add hatchling build backend, generate uv.lock, and publish via uv to Test PyPI and PyPI.
• Replace requirements.txt in a Keboola component with pyproject.toml, update Dockerfile to copy pyproject.toml + uv.lock and run uv sync in the image.
• Replace flake8 configuration with a minimal ruff config (line-length, extend-select I) and run ruff in CI and locally.
• Update GitHub Actions: install uv, run uv sync --all-groups --frozen, run tests with uv run pytest, and publish with uv publish.