Skip to content

Contributing to Mistaber

Welcome! We appreciate your interest in contributing to Mistaber, the formal symbolic reasoning system for computational halacha.

Ways to Contribute

  • 🐛 Report bugs - Open an issue describing the problem
  • 💡 Suggest features - Open an issue with your idea
  • 📖 Improve documentation - Fix typos, add examples, clarify explanations
  • 🧪 Add tests - Increase coverage for edge cases
  • 🔧 Submit code - Fix bugs or implement features

Development Setup

Prerequisites

  • Python 3.10 or higher
  • Clingo ASP solver (5.6.0+)

Installation

# Clone the repository
git clone https://github.com/BrainyBlaze/mistraber.git
cd mistaber

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Verify installation
mistaber --help

Running Tests

# Run all tests
pytest

# Run specific module tests
pytest tests/engine/

# Run with coverage
pytest --cov=mistaber

# Stop on first failure (useful for debugging)
pytest -x --tb=short

Code Quality Checks

# Linting
ruff check .

# Auto-fix linting issues
ruff check . --fix

# Type checking
mypy mistaber/

Pull Request Process

  1. Fork the repository on GitHub
  2. Clone your fork locally
  3. Create a branch for your changes: 
    git checkout -b feature/your-feature-name
  4. Make your changes with tests
  5. Run quality checks: 
    pytest && ruff check . && mypy mistaber/
  6. Commit with a clear message following Conventional Commits:
  7. feat: add new feature
  8. fix: resolve bug in X
  9. docs: update README
  10. refactor: restructure module Y
  11. test: add tests for Z
  12. Push to your fork and open a Pull Request

Code Style

  • Line length: 100 characters maximum
  • Type hints: Required for all public functions
  • Docstrings: Required for public modules, classes, and functions
  • Imports: Sorted by ruff (stdlib, third-party, local)
  • Follow existing patterns in the codebase

Domain Knowledge

Mistaber deals with halachic (Jewish legal) reasoning. If you're unfamiliar with the domain:

Don't worry if you're not a halacha expert! Many contributions (tests, documentation, tooling) don't require deep domain knowledge.

Commit Message Guidelines

We follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types: feat, fix, docs, style, refactor, test, build, ci, chore

Examples: - feat(engine): add support for sfek sfeika resolution - fix(cli): handle missing ontology path gracefully - docs(tutorials): add machloket encoding example

Questions?

  • Open an issue with the "question" label
  • Check existing discussions (if enabled)

Code of Conduct

Please read and follow our Code of Conduct.

Thank you for contributing to Mistaber! 🙏