Contributing to FastKit Core

Thank you for your interest in contributing! This guide walks you through everything you need — from setting up your development environment to getting your pull request merged.

Repository Issues Discussions Contribute

Ways to Contribute

Every contribution matters, no matter how big or small. Here are the ways you can help:

Report bugs

Found something that doesn't work? Open an issue with steps to reproduce.

Suggest features

Have an idea for a new pattern or mixin? Start a GitHub Discussion.

Submit code

Fix bugs, implement features, or improve performance with a pull request.

Improve docs

Clearer explanations, better examples, or fixing typos — all welcome.

Help others

Answer questions in GitHub Issues and Discussions.

Before starting on a large feature, open an issue or discussion first to align on scope and approach — it saves everyone time.

Development Setup

Fork and clone

bash

# 1. Fork on GitHub — click the Fork button at
#    https://github.com/fastkit-org/fastkit-core

# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/fastkit-core.git
cd fastkit-core

# 3. Add upstream remote
git remote add upstream https://github.com/fastkit-org/fastkit-core.git

# 4. Verify
git remote -v

Install dependencies

bash

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Create venv and install dev dependencies
uv venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

bash

python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -e ".[dev]"

bash

poetry install --with dev

Verify setup

bash

pytest                         # all tests pass
ruff check fastkit_core        # no linting issues
black --check fastkit_core     # code is formatted

Making Changes

Branch naming

Always create a new branch from an up-to-date main:

bash

git checkout main
git pull upstream main
git checkout -b feature/your-feature-name

feature/ add-soft-delete-mixin

fix/ repository-pagination-bug

docs/ update-api-examples

refactor/ simplify-validation-layer

Pre-commit checklist

bash

black fastkit_core tests       # format
isort fastkit_core tests       # sort imports
ruff check fastkit_core tests  # lint
pytest                         # tests
mypy fastkit_core              # type check (optional)

Pre-commit hooks (optional)

Automate the checklist above on every commit:

bash

pip install pre-commit
pre-commit install

yaml

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.13.0
    hooks:
      - id: mypy
        additional_dependencies: [pydantic, types-requests]

Commit Messages

FastKit Core follows the Conventional Commits specification:

text

<type>(<scope>): <subject>

feat New feature

fix Bug fix

docs Documentation only

style Formatting, no logic change

refactor Code restructure, no new features

test Adding or updating tests

perf Performance improvement

chore Build, tooling, process changes

bash

feat(repository): add support for bulk operations
fix(validation): handle None values in custom validators
docs(installation): add uv installation instructions
test(database): add tests for soft delete mixin
refactor(services): simplify lifecycle hook dispatch

Testing

Running tests

bash

# All tests
pytest

# Specific file
pytest tests/test_repository.py

# Specific test
pytest tests/test_repository.py::test_filter_by_id

# With coverage report
pytest --cov=fastkit_core --cov-report=html
# open htmlcov/index.html

# Coverage in terminal
pytest --cov=fastkit_core --cov-report=term-missing

Target is >80% coverage for any new code. Check coverage before submitting your PR.

Writing tests

Test files mirror the source structure: fastkit_core/repository.py → tests/test_repository.py

python

import pytest
from fastkit_core.database import Repository

class TestRepository:

    def test_create_instance(self, db_session):
        """Test creating a new record."""
        repo = Repository(User, db_session)
        user = repo.create(email="test@example.com", name="Test")

        assert user.id is not None
        assert user.email == "test@example.com"

    def test_filter_by_id(self, db_session):
        """Test finding by ID returns the correct record."""
        repo  = Repository(User, db_session)
        user  = repo.create(email="test@example.com", name="Test")
        found = repo.find(user.id)

        assert found is not None
        assert found.id == user.id

Tests must be fast and independent

One test — one assertion of behavior

Use descriptive names — the test name IS the documentation

Use fixtures to avoid duplication

Never depend on other tests or shared state

Code Style

FastKit Core uses four tools for consistent code quality. Run them in this order before committing:

black Formatter

bash

black fastkit_core tests
black --check fastkit_core tests  # check only

isort Import sorter

bash

isort fastkit_core tests
isort --check-only fastkit_core tests

ruff Linter

bash

ruff check fastkit_core tests
ruff check --fix fastkit_core tests  # auto-fix

mypy Type checker

bash

mypy fastkit_core

Pull Requests

Before opening a PR

bash

# Sync with upstream
git checkout main
git pull upstream main
git checkout your-branch
git rebase main

# Push to your fork
git push origin your-branch

PR process

Create the PR

Go to github.com/fastkit-org/fastkit-core and click "Compare & pull request". Fill in the title and description using the template below.

Automated checks

CI runs tests, linting and type checks automatically. All checks must pass before review begins.

Code review

A maintainer reviews your code and may request changes. Respond promptly and update your branch by pushing new commits — don't force-push during review.

Merge

Once approved and all checks pass, your PR is merged into main and included in the next release.

PR template

markdown

## Description
Brief description of your changes.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Related Issue
Fixes #issue_number

## How Has This Been Tested?
- [ ] Test scenario 1
- [ ] Test scenario 2

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Hard-to-understand areas are commented
- [ ] Documentation updated if needed
- [ ] No new warnings
- [ ] All tests pass

Release Process

FastKit Core follows Semantic Versioning 2.0.0:

Version bump	When	Example
MAJOR	Incompatible API changes	`0.x.x → 1.0.0`
MINOR	New backwards-compatible feature	`0.3.2 → 0.4.0`
PATCH	Backwards-compatible bug fix	`0.3.2 → 0.3.3`

Release steps (maintainers only)

bash

# 1. Update version in pyproject.toml
# 2. Update CHANGELOG.md

# 3. Create and push git tag
git tag -a v0.4.0 -m "Release v0.4.0"
git push upstream v0.4.0

# GitHub Actions automatically publishes to PyPI

Thank you for contributing!

Every contribution — from a typo fix to a new feature — helps make FastKit Core better for the entire FastAPI community. We appreciate your time and effort.

Open an Issue Contact Us