Contributing to Zaojun¶

Thank you for your interest in contributing to Zaojun! This document provides guidelines and instructions for contributing to the project.

Code of Conduct¶

Please be respectful and considerate of others when contributing to Zaojun. We aim to foster an inclusive and welcoming community.

How to Contribute¶

Reporting Issues¶

If you find a bug or have a feature request:

Search existing issues to avoid duplicates
Create a new issue with a clear title and description
Include details:
Zaojun version (zaojun --version)
Python version (python --version)
Steps to reproduce (for bugs)
Expected vs actual behavior

Suggesting Features¶

We welcome feature suggestions! When proposing a feature:

Explain the problem it solves
Describe the proposed solution
Provide use cases or examples
Consider alternatives you've evaluated

Submitting Pull Requests¶

Fork the repository on Codeberg
Create a feature branch from main
Make your changes following our guidelines
Test your changes thoroughly
Submit a pull request with a clear description

Development Setup¶

Prerequisites¶

Python 3.11 or higher
uv package manager
Git

Installation¶

# Clone the repository
git clone https://codeberg.org/marvin8/zaojun.git
cd zaojun

# Install dependencies
uv sync --all-groups

Development Environment¶

Zaojun uses several development tools:

ruff: Code formatting and linting
ty: Type checking
pytest: Testing framework
nox: Automated testing across Python versions
prek: Pre-commit hooks
bump-my-version: Version bumping
git-cliff: Changelog generation from conventional commits

Development Workflow¶

Code Style¶

Zaojun follows strict code style guidelines:

Format code with ruff:
```
uv run ruff format src/
```
Check code quality:
```
uv run ruff check src/
```
Type checking with ty:
```
uv run ty check src/
```

Testing¶

Run tests to ensure your changes work correctly:

# Run all tests
uv run pytest tests/

# Run specific test file
uv run pytest tests/test_check_dependency.py

# Run with coverage
uv run pytest --cov=zaojun tests/

Pre-commit Hooks¶

Zaojun uses prek for pre-commit hooks. Install and run them:

# Install prek hooks
uv run prek install

# Run hooks manually
uv run prek run --all-files

Nox Sessions¶

Zaojun uses nox for automated testing across Python versions:

# Run all nox sessions
uv run nox

# Run specific session
uv run nox -s ruff
uv run nox -s ty
uv run nox -s pytest

Available nox sessions: - ruff: Code formatting and linting - ty: Type checking across Python versions - pytest: Testing with coverage - interrogate: Docstring coverage - complexipy: Code complexity analysis - pysentry: Supply chain integrity and vulnerability scanning - gitleaks: Secret detection - deptry: Dependency checking - dependency_versions: Check Zaojun's own dependencies

Code Structure¶

zaojun/
├── src/zaojun/           # Source code
│   └── __init__.py      # Main implementation
├── tests/               # Test files
├── docs/               # Documentation
├── pyproject.toml      # Project configuration
└── noxfile.py          # Nox configuration

Key Components¶

CLI Interface (src/zaojun/__init__.py):
Uses Cyclopts for command-line parsing
Main check() function handles dependency checking
Command-line options defined with Annotated and Parameter
Dependency Checking:
check_dependency(): Checks individual dependencies
process_dependencies(): Processes lists of dependencies
get_latest_pypi_version(): Fetches versions from PyPI
Version Parsing:
Uses packaging library for version parsing
Handles various version constraint formats
Validates dependency specifications

Documentation¶

Building Documentation¶

Zaojun uses mkdocs for documentation:

# Install documentation dependencies
uv sync --group docs

# Serve documentation locally
uv run mkdocs serve

# Build documentation
uv run mkdocs build

Documentation Structure¶

docs/docs/: Documentation source files
mkdocs.yml: MkDocs configuration
API documentation is auto-generated from docstrings

Adding Documentation¶

Update existing files in docs/docs/
Add new files to appropriate sections
Update mkdocs.yml navigation if adding new sections
Use Markdown with mkdocs-material extensions
Include code examples where helpful

Changelog Management¶

Zaojun uses git-cliff for changelog generation from conventional commits, and bump-my-version to update the version in pyproject.toml.

Release Process¶

Bump version with bump-my-version (updates pyproject.toml, commits, tags)
Publish to PyPI automatically via Woodpecker CI on tag push

Versioning¶

Zaojun follows SemVer versioning: - Format: MAJOR.MINOR.PATCH - Example: 1.0.0

Branch Strategy¶

main: Stable release branch
feature/*: Feature branches
bugfix/*: Bug fix branches
docs/*: Documentation updates

Commit Messages¶

Use clear, descriptive commit messages:

feat: Add support for multiple package indexes
^--^  ^---------------------------------------^
|     |
|     +-> Summary in present tense
|
+-------> Type: feat, fix, docs, style, refactor, test, chore

Common commit types: - feat: New feature - fix: Bug fix - docs: Documentation changes - style: Code style changes (formatting, etc.) - refactor: Code refactoring - test: Test-related changes - chore: Maintenance tasks

Review Process¶

Automated checks run on all pull requests
Code review by maintainers
Address feedback and make requested changes
Merge when approved

Getting Help¶

If you need help contributing:

Check the documentation at marvin8.codeberg.page/zaojun
Look at existing issues and pull requests
Ask in discussions (if available)
Contact maintainers through Codeberg

Recognition¶

Contributors are recognized in: - Codeberg contributors list - Release notes - Documentation (when appropriate)

Thank you for contributing to Zaojun! Your help makes the project better for everyone.