Skip to content

Contributing

Thank you for your interest in contributing to logicblocks.event.store! This document provides guidelines and instructions for contributing.

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behaviour to maintainers@infrablocks.io.

Before submitting a bug report:

  1. Check the existing issues to avoid duplicates
  2. Collect information about the bug:
    • Stack trace and error messages
    • Python version (python --version)
    • Package version (pip show logicblocks.event.store)
    • Steps to reproduce the issue
    • Expected vs actual behaviour

Submit bug reports via GitHub Issues.

Feature requests are welcome. Please:

  1. Check existing issues and discussions first
  2. Clearly describe the use case and motivation
  3. Provide examples of how the feature would be used
  1. Fork the repository
  2. Create a feature branch from main
  3. Make your changes following the guidelines below
  4. Submit a pull request
  • mise - for tool version management
  • Docker - for running integration tests (PostgreSQL)
  1. Clone your fork:

    Terminal window
    git clone https://github.com/<your-username>/event.store.git
    cd event.store
  2. Install tools and dependencies:

    Terminal window
    mise install
    mise run dependencies:install

    This installs:

    • Python 3.13
    • uv (package manager)
    • All project dependencies
  3. Verify your setup:

    Terminal window
    mise run check

The project has three test suites:

Terminal window
# Unit tests (no external dependencies)
mise run test:unit
# Integration tests (requires PostgreSQL via Docker)
mise run test:integration
# Component tests (requires PostgreSQL via Docker)
mise run test:component
# All tests
mise run test
# Run a specific test class
mise run test:unit[TestClassName]

Integration and component tests automatically provision a PostgreSQL container via Docker Compose.

Terminal window
# Run all checks
mise run check
# Individual checks
mise run lint:check # Linting (ruff)
mise run format:check # Formatting (ruff)
mise run types:check # Type checking (pyrefly)
# Auto-fix issues
mise run fix # Run all fixers
mise run lint:fix # Fix linting issues
mise run format:fix # Fix formatting issues

Run the complete build pipeline (lint, format, type check, build, all tests):

Terminal window
mise run

This project follows TDD strictly. For every change:

  1. Red: Write a failing test first
  2. Green: Implement the minimum code to pass the test
  3. Refactor: Improve the code while keeping tests green

Target Python 3.13+. Use modern Python features:

# Use built-in generics
def process(items: dict[str, list[int]]) -> None: ...
# Use new generic syntax
class Repository[T]:
def get(self, id: str) -> T: ...
# Use TypedDict for complex parameters
class Options(TypedDict):
timeout: NotRequired[int]
retries: int
  • Use type hints for public APIs
  • Prefer immutable protocols from collections.abc (e.g., Mapping over dict)
  • Use @overload for functions with multiple signatures
  • Let Python infer types where obvious
  • Avoid redundant comments; let code be self-documenting
  • Use clear, descriptive names instead of comments
  • Only comment non-obvious, risky behaviour

Follow SOLID principles and favour:

  • Composition over inheritance
  • Small, focused classes and functions
  • Dependency injection
  • Immutability where practical
  • One assertion per test where practical
  • Clear, descriptive test names
  • Follow existing patterns in the codebase
  • Use parameterised tests for variations
  • Build complete expected results and assert equality
  1. Ensure all tests pass: mise run test
  2. Ensure code quality checks pass: mise run check
  3. Add a changelog fragment (see below)
  4. Update documentation if needed

This project uses scriv for changelog management. For user-facing changes:

  1. Create a changelog fragment:

    Terminal window
    mise run changelog:fragment:create
  2. Edit the generated file in changelog.d/ to describe your change

  3. Uncomment the appropriate section (Added, Changed, Fixed, etc.)

  4. Delete sections you don’t use

Fragment categories:

  • Added: New features
  • Changed: Changes to existing functionality
  • Deprecated: Features marked for removal
  • Removed: Removed features
  • Fixed: Bug fixes
  • Security: Security-related changes
  • Keep PRs focused on a single concern
  • Write a clear description of what and why
  • Reference related issues
  • Document breaking changes prominently with migration guidance
  • Respond to review feedback promptly

All submissions require review. Maintainers will:

  1. Review code quality and test coverage
  2. Verify adherence to project guidelines
  3. Test the changes locally if needed
  4. Provide feedback or approve

By contributing, you agree that your contributions will be licensed under the MIT License.