# Contributing to WalkXR AI

First off, thank you for considering contributing to WalkXR AI! Your help is essential for creating a robust and impactful platform.

This document provides guidelines for contributing to the project. Please read it carefully to ensure a smooth and effective collaboration process.

## Table of Contents

- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Reporting Bugs and Suggesting Features](#reporting-bugs-and-suggesting-features)
  - [Bug Reports](#bug-reports)
  - [Feature Requests](#feature-requests)
- [Development Workflow](#development-workflow)
  - [Branching Strategy](#branching-strategy)
  - [Making Changes](#making-changes)
  - [Commit Messages](#commit-messages)
  - [Pull Requests (PRs)](#pull-requests-prs)
- [Coding Standards](#coding-standards)
  - [Python Style](#python-style)
  - [Type Hinting](#type-hinting)
  - [Documentation Strings (Docstrings)](#documentation-strings-docstrings)
- [Testing](#testing)
- [Setting Up Your Development Environment](#setting-up-your-development-environment)

## Code of Conduct

This project and everyone participating in it is governed by a Code of Conduct (TODO: Link to or create a Code_of_Conduct.md). By participating, you are expected to uphold this code. Please report unacceptable behavior.

## Getting Started

Before you begin:
1.  Ensure you have a GitHub account.
2.  Familiarize yourself with the project by reading the [README.md](../README.md).
3.  Set up your [development environment](#setting-up-your-development-environment) as described in the README.

## Reporting Bugs and Suggesting Features

We use GitHub Issues to track bugs and feature requests.

### Bug Reports

If you find a bug, please ensure the bug has not already been reported by searching on GitHub under [Issues](https://github.com/VerseBuilding/WalkXR-AI/issues). If you're unable to find an open issue addressing the problem, open a new one using our [**Bug Report Template**](./.github/ISSUE_TEMPLATE/bug_report.md).

### Feature Requests

If you have an idea for a new feature or an enhancement to an existing one, please check the [Issues](https://github.com/VerseBuilding/WalkXR-AI/issues) to see if it has been suggested before. If not, create a new issue using our [**Feature Request Template**](./.github/ISSUE_TEMPLATE/feature_request.md).

## Development Workflow

### Branching Strategy

We follow a Gitflow-like branching model:

-   **`main`**: This branch represents the latest stable release. Direct commits to `main` are not allowed. Merges to `main` happen from `develop` during a release process.
-   **`develop`**: This is the primary development branch. All feature branches are created from `develop` and merged back into `develop`. This branch should always be in a state that could potentially be released.
-   **Feature Branches (`feature/<feature-name>`):** For new features. Branched from `develop`.
    -   Example: `feature/vulnerable-conversation-agent`
-   **Bugfix Branches (`fix/<bug-name>`):** For fixing bugs. Branched from `develop` (or `main` for hotfixes, though less common for this stage).
    -   Example: `fix/ingestion-unicode-error`
-   **Chore Branches (`chore/<task-name>`):** For routine tasks, refactoring, or documentation updates that don't add features or fix bugs.
    -   Example: `chore/update-readme-setup`

### Making Changes

1.  **Fork the Repository (if you are an external contributor):** Click the "Fork" button on the GitHub repository page. Clone your fork locally.
2.  **Clone the Repository (if you are a team member with write access):** Clone the main repository directly.
3.  **Create a New Branch:**
    ```bash
    git checkout develop
    git pull origin develop # Ensure your develop branch is up-to-date
    git checkout -b <branch-type>/<descriptive-branch-name>
    ```
4.  **Make Your Changes:** Write your code, add tests, and ensure all checks pass locally.
5.  **Commit Your Changes:** Follow the [Commit Messages](#commit-messages) guidelines.
    ```bash
    git add .
    git commit -m "Your detailed commit message"
    ```
6.  **Push Your Branch to GitHub:**
    ```bash
    git push origin <branch-type>/<descriptive-branch-name>
    ```
7.  **Open a Pull Request:** See [Pull Requests (PRs)](#pull-requests-prs).

### Commit Messages

We strive for clear and conventional commit messages. Please follow these guidelines:

-   **Format:** Start with a type, followed by an optional scope, and then a colon and a space, followed by a subject line. The subject line should be a concise description of the change (max 50 characters).
    ```
    <type>(<scope>): <subject>
    ```
    -   **Types:** `feat` (new feature), `fix` (bug fix), `docs` (documentation), `style` (formatting, missing semi colons, etc; no code change), `refactor` (refactoring production code), `test` (adding/refactoring tests; no production code change), `chore` (updating grunt tasks etc; no production code change).
    -   **Scope (Optional):** The part of the codebase affected (e.g., `agent`, `rag`, `readme`).
-   **Body (Optional):** Provide more context after the subject line, separated by a blank line. Explain *what* and *why* vs. *how*.
-   **Footer (Optional):** Reference issue numbers (e.g., `Fixes #123`).

**Example Commit Message:**
```
feat(agent): Add initial Vulnerable Conversation Agent template

This commit introduces a basic structure for the Vulnerable Conversation
Agent, including placeholder methods for core logic and interaction
with the RAG pipeline.

Refs #42
```

### Pull Requests (PRs)

When you're ready to merge your changes, open a Pull Request (PR) against the `develop` branch.

-   **Use the PR Template:** Fill out our [**Pull Request Template**](./.github/PULL_REQUEST_TEMPLATE.md) on GitHub. It will guide you through describing your changes, linking to issues, and outlining your testing process.
-   **Clear Title and Description:** Make sure your PR title and description clearly explain the purpose of your changes.
-   **Link to Issues:** If your PR addresses an open issue, link it (e.g., `Fixes #123`).
-   **Self-Review:** Before submitting, review your own changes (the "Files changed" tab on GitHub).
-   **Ensure Checks Pass:** All automated checks (linting, typing, tests - once CI is set up) must pass before a PR can be merged.
-   **Respond to Feedback:** Be prepared to address comments and feedback from reviewers.

## Coding Standards

### Python Style
-   Follow **PEP 8** guidelines.
-   We use **Ruff** for linting and formatting. Configure your IDE to use Ruff, or run it manually before committing:
    ```bash
    poetry run ruff check . --fix
    poetry run ruff format .
    ```

### Type Hinting
-   Use **PEP 484** type hints for all function signatures and variables where appropriate.
-   We use **MyPy** for static type checking. Run it manually before committing:
    ```bash
    poetry run mypy src
    ```

### Documentation Strings (Docstrings)
-   Write clear and concise docstrings for all modules, classes, functions, and methods.
-   Follow **PEP 257** conventions.
-   Use a consistent style (e.g., Google style or NumPy style).
    **Example (Google Style):**
    ```python
    def my_function(param1: int, param2: str) -> bool:
        """Does something interesting.

        Args:
            param1: The first parameter.
            param2: The second parameter.

        Returns:
            True if successful, False otherwise.
        """
        # ... function body ...
        return True
    ```

## Testing

-   Write unit tests for new functionality in the `tests/` directory.
-   Aim for high test coverage.
-   Ensure all tests pass locally before pushing changes (`poetry run pytest` - once pytest is added and tests are written).

## Setting Up Your Development Environment

Detailed instructions for setting up your development environment are in the main [README.md](../README.md) under the "Getting Started: Environment Setup" section.