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!
