Contributing

Contributing Guide

Thank you for your interest in contributing to Mizan Core Engine! Whether you are fixing bugs, adding features, or improving documentation, your contributions are welcome.

Getting Started

Fork and Clone

bash

git clone https://github.com/YOUR_USERNAME/mizan.git
cd mizan
git remote add upstream https://github.com/ahmetabdullahgultekin/Mizan.git

Set Up Development Environment

bash

python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
pre-commit install

Start Services and Run Tests

bash

docker-compose up -d db redis
alembic upgrade head
pytest

Branch Naming

feature/add-root-extraction

New features

fix/abjad-calculation-error

Bug fixes

docs/update-api-reference

Documentation

refactor/simplify-letter-counter

Refactoring

test/add-property-tests

Tests

chore/update-dependencies

Maintenance

Coding Standards

Python Style

PEP 8, type hints for all signatures, max 100 char lines, Ruff for linting and formatting.

Architecture

Hexagonal Architecture. Domain layer has no external dependencies. Use dependency injection.

Testing

Test one thing per function. Include positive and negative cases. Use fixtures for setup.

Scholarly Accuracy

Accuracy is paramount. Verify against authoritative sources. Document references in code.

Commit Messages

Follow the Conventional Commits format:

text

type(scope): brief description

Longer explanation if needed.

Fixes #123

featNew feature

fixBug fix

docsDocumentation

refactorCode restructuring

testAdding tests

choreMaintenance

Pull Request Checklist

All tests pass (pytest)
Code follows project style guidelines (ruff check, ruff format)
Type checking passes (mypy src/mizan)
Documentation is updated if needed
Commit messages are clear and follow conventional commits
PR description explains the changes and why

Scholarly Accuracy

Mizan is a scholarly tool. Accuracy is paramount. Before modifying any calculation or counting logic:

Research the standard and verify against authoritative sources
Document your sources in code comments
Test against known verified values
Update STANDARDS.py if documenting new standards

Authoritative sources: Tanzil.net, Quran.com, IslamWeb, classical Islamic scholarship (Ibn Kathir, etc.)

بارك الله فيكم

May Allah bless you - Thank you for contributing!

View on GitHub Documentation

Getting Started

Fork and Clone

bash

git clone https://github.com/YOUR_USERNAME/mizan.git
cd mizan
git remote add upstream https://github.com/ahmetabdullahgultekin/Mizan.git

Set Up Development Environment

bash

python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
pre-commit install

Start Services and Run Tests

bash

docker-compose up -d db redis
alembic upgrade head
pytest

Coding Standards

Python Style

PEP 8, type hints for all signatures, max 100 char lines, Ruff for linting and formatting.

Architecture

Hexagonal Architecture. Domain layer has no external dependencies. Use dependency injection.

Testing

Test one thing per function. Include positive and negative cases. Use fixtures for setup.

Scholarly Accuracy

Accuracy is paramount. Verify against authoritative sources. Document references in code.

Scholarly Accuracy

Mizan is a scholarly tool. Accuracy is paramount. Before modifying any calculation or counting logic:

Research the standard and verify against authoritative sources
Document your sources in code comments
Test against known verified values
Update STANDARDS.py if documenting new standards

Authoritative sources: Tanzil.net, Quran.com, IslamWeb, classical Islamic scholarship (Ibn Kathir, etc.)