Development Guide
=================

This guide covers setting up a development environment, coding standards, testing, and contribution workflows.

Development Setup
-----------------

Prerequisites
~~~~~~~~~~~~~

* Python >= 3.12
* Git
* Visual Studio with C++ tools (Windows) or build essentials (Linux/macOS)

Clone Repository
~~~~~~~~~~~~~~~~

.. code-block:: bash

   git clone https://github.com/wimarka-uic/WiMarka.git
   cd WiMarka

Create Virtual Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   python -m venv venv
   
   # Activate
   # Windows:
   venv\\Scripts\\activate
   
   # macOS/Linux:
   source venv/bin/activate

Install in Development Mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   pip install -e .

This installs WiMarka in "editable" mode, allowing code changes to take effect immediately.

Project Structure
-----------------

.. code-block:: text

   WiMarka/
   ├── wimarka/              # Main package
   │   ├── __init__.py
   │   ├── main.py
   │   ├── cli.py
   │   ├── config.py
   │   ├── tasks/            # Task modules
   │   └── utils/            # Utilities
   ├── test/                 # Test files
   ├── docs/                 # Documentation
   ├── setup.py              # Package configuration
   ├── requirements.txt      # Dependencies
   └── README.md

Coding Standards
----------------

Style Guide
~~~~~~~~~~~

Follow PEP 8 Python style guide:

* 4 spaces for indentation
* Max line length: 100 characters
* Use descriptive variable names

Type Hints
~~~~~~~~~~

Use type hints for function signatures:

.. code-block:: python

   def evaluate(src: str, tgt: str) -> List[str]:
       """Evaluate translation."""
       pass

Docstrings
~~~~~~~~~~

Use Google-style docstrings:

.. code-block:: python

   def function_name(param1: str, param2: int) -> bool:
       """Brief description.
       
       Detailed description if needed.
       
       Args:
           param1: Description of param1
           param2: Description of param2
       
       Returns:
           Description of return value
       """
       pass

Testing
-------

Running Tests
~~~~~~~~~~~~~

.. code-block:: bash

   cd test
   python main.py

Writing Tests
~~~~~~~~~~~~~

Add test files to ``test/`` directory.

Example test:

.. code-block:: python

   def test_evaluation():
       """Test basic evaluation."""
       from wimarka.main import wmk_eval
       
       wmk_eval('test_src.txt', 'EN', 'test_tgt.txt', 'CEB')
       # Assert expected behavior

Contributing
------------

Workflow
~~~~~~~~

1. Fork the repository
2. Create feature branch
3. Make changes
4. Test thoroughly
5. Submit pull request

Pull Request Guidelines
~~~~~~~~~~~~~~~~~~~~~~~~

* Clear description of changes
* Reference related issues
* Include tests if applicable
* Update documentation

Git Commit Messages
~~~~~~~~~~~~~~~~~~~

Use clear, descriptive commit messages:

.. code-block:: text

   Add error detection for Ilocano
   
   - Implement ILO-specific error patterns
   - Add test cases
   - Update documentation

See Also
--------

* `Contributing Guidelines <https://github.com/wimarka-uic/WiMarka/blob/main/CONTRIBUTING.md>`_
* :doc:`extending` - Extension guide
* :doc:`architecture` - System architecture