Skip to content

Contributing

Thank you for contributing to UniFace!

Quick Start

We use uv for reproducible dev installs (lockfile-pinned).

# Install uv first: https://docs.astral.sh/uv/getting-started/installation/

# Clone
git clone https://github.com/yakhyo/uniface.git
cd uniface

# Install runtime + cpu + dev extras from uv.lock (--extra gpu for CUDA)
uv sync --extra cpu --extra dev

# Run tests
uv run pytest

Code Style

We use Ruff for formatting:

ruff format .
ruff check . --fix

Guidelines:

  • Line length: 120
  • Python 3.10+ type hints
  • Google-style docstrings

Pre-commit Hooks

pre-commit is included in the [dev] extra, so uv sync already installs it.

uv run pre-commit install
uv run pre-commit run --all-files

Commit Messages

We follow Conventional Commits:

<type>: <short description>
Type When to use
feat New feature or capability
fix Bug fix
docs Documentation changes
style Formatting, whitespace (no logic change)
refactor Code restructuring without changing behavior
perf Performance improvement
test Adding or updating tests
build Build system or dependencies
ci CI/CD and pre-commit configuration
chore Routine maintenance and tooling

Examples:

feat: Add gaze estimation model
fix: Correct bounding box scaling for non-square images
ci: Add nbstripout pre-commit hook
docs: Update installation instructions

Pull Request Process

  1. Fork the repository
  2. Create a feature branch
  3. Write tests for new features
  4. Ensure tests pass
  5. Submit PR with clear description

Adding New Models

  1. Create model class in appropriate submodule
  2. Add weight constants to uniface/constants.py
  3. Export in __init__.py files
  4. Write tests in tests/
  5. Add example in tools/ or notebooks

Releases

Releases are automated via GitHub Actions. Maintainers trigger Actions → Release Pipeline → Run workflow with a PEP 440 version (e.g. 0.7.0, 0.7.0rc1). The pipeline runs tests, bumps pyproject.toml + uniface/__init__.py, tags the commit, publishes to PyPI, and creates a GitHub Release. Docs redeploy only for stable releases.

See CONTRIBUTING.md for the full process.

Questions?

Open an issue on GitHub.