Thank you for your interest in contributing to Zeeker! This guide will help you get started with development in the workspace architecture.
- Workspace Structure
- Development Setup
- Development Workflow
- Testing
- Code Style
- Making Changes
- Publishing (Maintainers)
Zeeker is organized as a uv workspace with multiple packages:
zeeker/
├── packages/
│ ├── zeeker/ # Core framework
│ │ ├── zeeker/ # Source code
│ │ ├── tests/ # Tests
│ │ └── pyproject.toml # Package config
│ │
│ └── zeeker-common/ # Shared utilities
│ ├── zeeker_common/ # Source code
│ ├── tests/ # Tests (optional)
│ └── pyproject.toml # Package config
│
├── examples/ # Example projects
│ ├── legal-news/ # Advanced example
│ └── datasets/ # Simple example
│
├── .github/workflows/ # CI/CD
│ ├── test.yml # Test all packages
│ ├── publish-zeeker.yml # Publish zeeker
│ └── publish-common.yml # Publish zeeker-common
│
├── pyproject.toml # Workspace configuration
├── pytest.ini # Test configuration
└── README.md # Main documentation
- Python 3.12 or higher
- uv - Fast Python package manager
-
Fork the repository on GitHub
-
Clone your fork:
git clone https://github.com/YOUR_USERNAME/zeeker.git cd zeeker -
Install uv if you haven't already:
# On macOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh # On Windows powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
-
Install all workspace dependencies:
uv sync
This creates a unified
.venvat the workspace root and installs all packages in editable mode.
# Run all tests across all packages
uv run pytest
# Run specific package tests
uv run pytest packages/zeeker/tests
uv run pytest packages/zeeker-common/tests
# Run with specific markers
uv run pytest -m unit
uv run pytest -m integration
uv run pytest -m "not slow"
# Run with coverage
uv run pytest --covWe use Black for code formatting:
# Check formatting
uv run black --check .
# Apply formatting
uv run black .We use Ruff for linting:
# Check for issues
uv run ruff check .
# Auto-fix issues
uv run ruff check --fix .The CLI is available via uv run:
# Test CLI
uv run zeeker --help
# Test project creation
uv run zeeker init test-project
cd test-project
uv run zeeker add test-resource
uv run zeeker buildTests are organized by package:
packages/zeeker/tests/- Core framework testspackages/zeeker-common/tests/- Utilities tests (if needed)
We use pytest markers to categorize tests:
@pytest.mark.unit- Unit tests@pytest.mark.integration- Integration tests@pytest.mark.cli- CLI interface tests@pytest.mark.slow- Tests that take longer to run
Example:
import pytest
@pytest.mark.unit
def test_project_manager():
# Test code here
pass# Run only unit tests
uv run pytest -m unit
# Run only fast tests
uv run pytest -m "not slow"
# Run a specific test file
uv run pytest packages/zeeker/tests/test_project.py
# Run a specific test
uv run pytest packages/zeeker/tests/test_project.py::test_specific_function- Line length: 100 characters
- String quotes: Double quotes preferred
- Imports: Organized with
ruff(E, F, W, I) - Type hints: Use where it improves clarity
Use Google-style docstrings:
def fetch_data(existing_table: Optional[Table]) -> List[Dict[str, Any]]:
"""Fetch data for the resource.
Args:
existing_table: sqlite-utils Table object or None
Returns:
List of dictionaries containing data to insert
Raises:
ValueError: If data validation fails
"""
pass-
Create a feature branch:
git checkout -b feature/my-feature
-
Make your changes in the appropriate package:
- Core framework changes →
packages/zeeker/zeeker/ - Utility changes →
packages/zeeker-common/zeeker_common/ - Tests →
packages/*/tests/
- Core framework changes →
-
Add tests for your changes
-
Run the test suite:
uv run pytest
-
Format and lint your code:
uv run black . uv run ruff check --fix .
-
Commit your changes:
git add . git commit -m "Add feature: description of your changes"
-
Push to your fork:
git push origin feature/my-feature
-
Create a Pull Request on GitHub
Use clear, descriptive commit messages:
- Good: "Add async support for resource fetching"
- Good: "Fix schema conflict detection for JSON columns"
- Bad: "Fix bug"
- Bad: "Update code"
- Title: Clear description of what the PR does
- Description: Explain why the change is needed and how it works
- Tests: Include tests for new functionality
- Documentation: Update relevant documentation
- Small PRs: Keep PRs focused on a single feature or fix
To core zeeker package:
cd packages/zeeker
uv add package-nameTo zeeker-common:
cd packages/zeeker-common
uv add package-nameTo workspace dev dependencies:
Edit root pyproject.toml:
[tool.uv]
dev-dependencies = [
"pytest>=8.4.0",
"new-package>=1.0.0",
]Then run uv sync.
Since all packages are installed in editable mode, changes are immediately reflected:
# In packages/zeeker-common/zeeker_common/utils.py
def new_utility():
return "test"
# In packages/zeeker/zeeker/core/project.py
from zeeker_common import new_utility # Works immediately!Test your changes with the example projects:
cd examples/legal-news
uv sync # Sync within example
uv run zeeker buildUpdate version in respective pyproject.toml:
# packages/zeeker/pyproject.toml
[project]
version = "0.6.1"
# packages/zeeker-common/pyproject.toml
[project]
version = "0.1.1"Publishing is automated via GitHub Actions on release.
Manual publishing (if needed):
# Build zeeker
cd packages/zeeker
uv build
uv publish --token $PYPI_TOKEN
# Build zeeker-common
cd packages/zeeker-common
uv build
uv publish --token $PYPI_TOKEN_COMMON- Update version numbers
- Update CHANGELOG (if you maintain one)
- Commit version bumps
- Create git tag:
git tag zeeker-v0.6.1 git tag zeeker-common-v0.1.1 git push --tags
- Create GitHub Release (triggers auto-publish)
- Issues: https://github.com/zeeker-sg/cli/issues
- Discussions: https://github.com/zeeker-sg/cli/discussions
- Email: houfu@outlook.sg
Be respectful and constructive in all interactions. We're all here to build something useful together.
Thank you for contributing to Zeeker! 🚀