WalkXR-AI / CONTRIBUTING.md
CONTRIBUTING.md
Raw

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

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.
  3. Set 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. If you're unable to find an open issue addressing the problem, open a new one using our Bug Report Template.

Feature Requests

If you have an idea for a new feature or an enhancement to an existing one, please check the Issues to see if it has been suggested before. If not, create a new issue using our Feature Request Template.

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: 
    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 guidelines. 
    git add .
git commit -m "Your detailed commit message"
  6. Push Your Branch to GitHub: 
    git push origin <branch-type>/<descriptive-branch-name>
  7. Open a Pull Request: See 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 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: 
    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: 
    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): 
    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 under the "Getting Started: Environment Setup" section.

Powered by GitFront