Contributing
============

We welcome contributions to wosecopy! This guide will help you get started.

Getting Started
---------------

1. Fork the repository on GitHub
2. Clone your fork locally
3. Create a virtual environment
4. Install in development mode

.. code-block:: bash

   git clone https://github.com/yourusername/wosecopy.git
   cd wosecopy
   python -m venv venv
   source venv/bin/activate  # Windows: venv\Scripts\activate
   pip install -e ".[dev]"

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

Install Development Dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   pip install -e ".[dev]"

This installs:

* pytest (testing)
* pytest-cov (coverage)
* black (code formatting)
* flake8 (linting)
* sphinx (documentation)

Download Language Models
~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   python -m spacy download en_core_web_lg
   python -m spacy download de_core_news_lg

Code Style
----------

We use Black for code formatting and follow PEP 8 guidelines.

Format Code
~~~~~~~~~~~

.. code-block:: bash

   black wosecopy/
   black tests/

Lint Code
~~~~~~~~~

.. code-block:: bash

   flake8 wosecopy/ tests/

Running Tests
-------------

Run All Tests
~~~~~~~~~~~~~

.. code-block:: bash

   pytest

Run with Coverage
~~~~~~~~~~~~~~~~~

.. code-block:: bash

   pytest --cov=wosecopy --cov-report=html

Run Specific Test File
~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   pytest tests/test_core.py

Run Specific Test
~~~~~~~~~~~~~~~~~

.. code-block:: bash

   pytest tests/test_core.py::TestwosecopyExtractor::test_initialization

Writing Tests
-------------

Test files should:

* Be in the ``tests/`` directory
* Start with ``test_``
* Use pytest fixtures from ``conftest.py``

Example Test
~~~~~~~~~~~~

.. code-block:: python

   import pytest
   from wosecopy import wosecopyExtractor

   def test_extract_nouns():
       extractor = wosecopyExtractor(language='en')
       nouns = extractor.extract_nouns("The dog runs.")
       assert 'dog' in nouns

Documentation
-------------

Build Documentation
~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   cd docs
   make html

View locally at ``docs/build/html/index.html``

Writing Documentation
~~~~~~~~~~~~~~~~~~~~~

* Use reStructuredText format
* Add docstrings to all public functions/classes
* Follow Google or NumPy docstring style
* Update relevant .rst files in ``docs/source/``

Submitting Changes
------------------

1. Create a Feature Branch
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   git checkout -b feature/my-new-feature

2. Make Your Changes
~~~~~~~~~~~~~~~~~~~~

* Write code
* Add tests
* Update documentation
* Run tests and linting

3. Commit Your Changes
~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   git add .
   git commit -m "Add feature: description"

Use clear commit messages:

* "Add feature: concept filtering"
* "Fix bug: handle empty graphs"
* "Update docs: add tutorial"

4. Push to Your Fork
~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   git push origin feature/my-new-feature

5. Create Pull Request
~~~~~~~~~~~~~~~~~~~~~~

* Go to GitHub
* Click "New Pull Request"
* Describe your changes
* Reference any related issues

Pull Request Guidelines
-----------------------

Your PR should:

* Have a clear description
* Include tests for new features
* Update documentation as needed
* Pass all CI checks
* Follow code style guidelines

Code Review Process
-------------------

1. Automated checks run (tests, linting)
2. Maintainers review your code
3. Discussion and revisions
4. Approval and merge

Types of Contributions
----------------------

Bug Reports
~~~~~~~~~~~

Submit bug reports as GitHub issues with:

* Description of the bug
* Steps to reproduce
* Expected vs actual behavior
* System information

Feature Requests
~~~~~~~~~~~~~~~~

Submit feature requests with:

* Use case description
* Proposed solution
* Alternative solutions considered

Code Contributions
~~~~~~~~~~~~~~~~~~

* Bug fixes
* New features
* Performance improvements
* Documentation improvements

Questions?
----------

* Open an issue for questions
* Check existing issues first
* Be respectful and patient

Thank You!
----------

Thank you for contributing to wosecopy!