Contributing
Thank you for your interest in contributing to logicblocks.event.store! This document provides guidelines and instructions for contributing.
Code of Conduct
Section titled “Code of Conduct”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.
How to Contribute
Section titled “How to Contribute”Reporting Bugs
Section titled “Reporting Bugs”Before submitting a bug report:
- Check the existing issues to avoid duplicates
- 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.
Suggesting Features
Section titled “Suggesting Features”Feature requests are welcome. Please:
- Check existing issues and discussions first
- Clearly describe the use case and motivation
- Provide examples of how the feature would be used
Submitting Changes
Section titled “Submitting Changes”- Fork the repository
- Create a feature branch from
main - Make your changes following the guidelines below
- Submit a pull request
Development Setup
Section titled “Development Setup”Prerequisites
Section titled “Prerequisites”Getting Started
Section titled “Getting Started”-
Clone your fork:
Terminal window git clone https://github.com/<your-username>/event.store.gitcd event.store -
Install tools and dependencies:
Terminal window mise installmise run dependencies:installThis installs:
- Python 3.13
- uv (package manager)
- All project dependencies
-
Verify your setup:
Terminal window mise run check
Running Tests
Section titled “Running Tests”The project has three test suites:
# 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 testsmise run test
# Run a specific test classmise run test:unit[TestClassName]Integration and component tests automatically provision a PostgreSQL container via Docker Compose.
Code Quality
Section titled “Code Quality”# Run all checksmise run check
# Individual checksmise run lint:check # Linting (ruff)mise run format:check # Formatting (ruff)mise run types:check # Type checking (pyrefly)
# Auto-fix issuesmise run fix # Run all fixersmise run lint:fix # Fix linting issuesmise run format:fix # Fix formatting issuesFull Build
Section titled “Full Build”Run the complete build pipeline (lint, format, type check, build, all tests):
mise runDevelopment Guidelines
Section titled “Development Guidelines”Test-Driven Development
Section titled “Test-Driven Development”This project follows TDD strictly. For every change:
- Red: Write a failing test first
- Green: Implement the minimum code to pass the test
- Refactor: Improve the code while keeping tests green
Code Style
Section titled “Code Style”Python Version
Section titled “Python Version”Target Python 3.13+. Use modern Python features:
# Use built-in genericsdef process(items: dict[str, list[int]]) -> None: ...
# Use new generic syntaxclass Repository[T]: def get(self, id: str) -> T: ...
# Use TypedDict for complex parametersclass Options(TypedDict): timeout: NotRequired[int] retries: intType Hints
Section titled “Type Hints”- Use type hints for public APIs
- Prefer immutable protocols from
collections.abc(e.g.,Mappingoverdict) - Use
@overloadfor functions with multiple signatures - Let Python infer types where obvious
Comments
Section titled “Comments”- Avoid redundant comments; let code be self-documenting
- Use clear, descriptive names instead of comments
- Only comment non-obvious, risky behaviour
Design Principles
Section titled “Design Principles”Follow SOLID principles and favour:
- Composition over inheritance
- Small, focused classes and functions
- Dependency injection
- Immutability where practical
Test Structure
Section titled “Test Structure”- 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
Pull Request Process
Section titled “Pull Request Process”Before Submitting
Section titled “Before Submitting”- Ensure all tests pass:
mise run test - Ensure code quality checks pass:
mise run check - Add a changelog fragment (see below)
- Update documentation if needed
Changelog Fragments
Section titled “Changelog Fragments”This project uses scriv for changelog management. For user-facing changes:
-
Create a changelog fragment:
Terminal window mise run changelog:fragment:create -
Edit the generated file in
changelog.d/to describe your change -
Uncomment the appropriate section (Added, Changed, Fixed, etc.)
-
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
PR Guidelines
Section titled “PR Guidelines”- 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
Review Process
Section titled “Review Process”All submissions require review. Maintainers will:
- Review code quality and test coverage
- Verify adherence to project guidelines
- Test the changes locally if needed
- Provide feedback or approve
Questions?
Section titled “Questions?”- Open a GitHub Discussion for questions
- Check existing issues and discussions
- Review the documentation
License
Section titled “License”By contributing, you agree that your contributions will be licensed under the MIT License.