Contributing ============ Thank you for your interest in contributing to the Persian library! This document provides guidelines and instructions for contributing. Getting Started --------------- Prerequisites ~~~~~~~~~~~~~ * Python 3.10 or higher * Git * Familiarity with pytest for testing * Understanding of Persian language processing Setting Up Development Environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. **Fork the repository** on GitHub 2. **Clone your fork**: .. code-block:: bash git clone https://github.com/YOUR_USERNAME/persian.git cd persian 3. **Create a virtual environment**: .. code-block:: bash python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate 4. **Install development dependencies**: .. code-block:: bash pip install -e ".[dev]" 5. **Verify installation**: .. code-block:: bash python -m pytest mypy persian Development Workflow -------------------- Creating a Feature Branch ~~~~~~~~~~~~~~~~~~~~~~~~~ Always create a new branch for your work: .. code-block:: bash git checkout -b feature/your-feature-name # or git checkout -b fix/your-bug-fix Code Style ~~~~~~~~~~ We use multiple tools to maintain code quality: **Black** (code formatting): .. code-block:: bash black persian tests **Ruff** (linting): .. code-block:: bash ruff check persian tests **isort** (import sorting): .. code-block:: bash isort persian tests **Flake8** (style checking): .. code-block:: bash flake8 persian tests **Run all checks**: .. code-block:: bash make lint # If using Makefile # Or manually: black persian tests && \ ruff check persian tests && \ isort persian tests && \ flake8 persian tests Type Checking ~~~~~~~~~~~~~ All code must pass mypy type checking: .. code-block:: bash mypy persian Add type hints to all functions: .. code-block:: python def convert_en_numbers(input_str: str) -> str: """Convert English digits to Persian digits.""" # Implementation Writing Tests ~~~~~~~~~~~~~ All new features and bug fixes must include tests. **Test file structure**: .. code-block:: text tests/ ├── test_core.py ├── test_utilities.py └── test_deprecation.py **Write a test**: .. code-block:: python import pytest import persian def test_convert_en_numbers(): """Test English to Persian number conversion.""" assert persian.convert_en_numbers("123") == "۱۲۳" assert persian.convert_en_numbers("") == "" def test_convert_en_numbers_validation(): """Test input validation.""" with pytest.raises(TypeError): persian.convert_en_numbers(123) with pytest.raises(ValueError): persian.convert_en_numbers(None) **Run tests**: .. code-block:: bash # Run all tests pytest # Run with coverage pytest --cov=persian --cov-report=html # Run specific test pytest tests/test_core.py::test_convert_en_numbers Documentation ~~~~~~~~~~~~~ Update documentation for any changes: 1. **Docstrings**: Use Google style docstrings .. code-block:: python def my_function(input_str: str) -> str: """One-line summary. Longer description if needed. Args: input_str: Description of parameter. Returns: Description of return value. Raises: TypeError: If input_str is not a string. ValueError: If input_str is None. Examples: >>> my_function("test") 'result' """ 2. **Update relevant .rst files** in ``docs/sphinx/`` 3. **Build documentation locally**: .. code-block:: bash cd docs/sphinx make html # View at docs/sphinx/_build/html/index.html Committing Changes ------------------ Commit Message Format ~~~~~~~~~~~~~~~~~~~~~ Write clear, descriptive commit messages: .. code-block:: text Short summary (50 chars or less) More detailed explanation if necessary. Wrap at 72 characters. - Bullet points are okay - Use present tense: "Add feature" not "Added feature" - Reference issues: "Fixes #123" or "Relates to #456" **Examples**: .. code-block:: text Add support for removing Arabic diacritics Implement remove_arabic_diacritics() function to strip tashkeel characters from Arabic/Persian text. Fixes #42 .. code-block:: text Fix spacing issue in convert_fa_spaces The function was not handling multiple consecutive spaces correctly. Updated regex pattern to match all cases. Fixes #67 Pre-commit Checklist ~~~~~~~~~~~~~~~~~~~~ Before committing, ensure: - [ ] Code follows style guidelines (Black, Ruff, isort) - [ ] All tests pass (``pytest``) - [ ] Type checking passes (``mypy persian``) - [ ] Coverage doesn't decrease - [ ] Documentation is updated - [ ] Commit message is clear Submitting a Pull Request -------------------------- Preparing Your PR ~~~~~~~~~~~~~~~~~ 1. **Update your branch**: .. code-block:: bash git fetch upstream git rebase upstream/main 2. **Push to your fork**: .. code-block:: bash git push origin feature/your-feature-name 3. **Create pull request** on GitHub PR Description Template ~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: markdown ## Description Brief description of changes ## Motivation Why is this change needed? ## Changes - List of changes made - Each on a new line ## Testing How was this tested? ## Checklist - [ ] Tests added/updated - [ ] Documentation updated - [ ] Type hints added - [ ] All tests pass - [ ] Code follows style guidelines Code Review Process ~~~~~~~~~~~~~~~~~~~ 1. Maintainers will review your PR 2. Address any requested changes 3. Once approved, your PR will be merged Types of Contributions ---------------------- Bug Fixes ~~~~~~~~~ Found a bug? Please: 1. **Check existing issues** to avoid duplicates 2. **Create an issue** describing the bug 3. **Submit a PR** with the fix and tests Feature Requests ~~~~~~~~~~~~~~~~ Have an idea for a new feature? 1. **Create an issue** to discuss the feature 2. **Wait for approval** before implementing 3. **Submit a PR** with implementation and tests Documentation ~~~~~~~~~~~~~ Documentation improvements are always welcome: * Fix typos * Improve examples * Add missing documentation * Clarify existing docs Performance Improvements ~~~~~~~~~~~~~~~~~~~~~~~~ Performance PRs should include: * Benchmarks showing improvement * Explanation of the optimization * Tests ensuring correctness Testing ------- Running the Full Test Suite ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash # Run all tests pytest # With coverage report pytest --cov=persian --cov-report=html --cov-report=term # Run benchmarks pytest tests/test_benchmark.py --benchmark-only Writing Good Tests ~~~~~~~~~~~~~~~~~~ * Test both success and failure cases * Use descriptive test names * Include edge cases * Test error handling .. code-block:: python def test_convert_en_numbers_empty_string(): """Empty string should return empty string.""" assert persian.convert_en_numbers("") == "" def test_convert_en_numbers_no_digits(): """String without digits should be unchanged.""" assert persian.convert_en_numbers("hello") == "hello" def test_convert_en_numbers_mixed_content(): """Mixed content should only convert digits.""" assert persian.convert_en_numbers("test 123") == "test ۱۲۳" Community Guidelines -------------------- Code of Conduct ~~~~~~~~~~~~~~~ * Be respectful and inclusive * Welcome newcomers * Provide constructive feedback * Focus on the code, not the person Getting Help ~~~~~~~~~~~~ * **GitHub Issues**: For bugs and feature requests * **GitHub Discussions**: For questions and general discussion * **Documentation**: Check docs first Recognition ~~~~~~~~~~~ Contributors will be: * Listed in the README * Credited in release notes * Thanked in the project Release Process --------------- For Maintainers ~~~~~~~~~~~~~~~ 1. Update version in ``pyproject.toml`` 2. Update ``CHANGELOG.md`` 3. Create release tag 4. Build and upload to PyPI 5. Create GitHub release Resources --------- * **Repository**: https://github.com/rezkam/persian * **Documentation**: https://persian.readthedocs.io * **Issue Tracker**: https://github.com/rezkam/persian/issues * **PyPI**: https://pypi.org/project/persian Thank You! ---------- Your contributions make this project better. Thank you for taking the time to contribute!