Contributing Guidelines

Thank you for your interest in contributing to AxisPy Engine! This document provides guidelines and instructions for contributing to the project.

Getting Started

Fork and Clone

Fork the repository on GitHub
Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/axispy.git
cd axispy

Add the upstream repository as a remote:

git remote add upstream https://github.com/Bayaola/axispy.git

Development Environment

Create a virtual environment:

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

Install dependencies:

pip install -r requirements.txt

Install the package in development mode:

pip install -e .

Run tests to verify setup:

pytest tests/

How to Contribute

Reporting Bugs

Before submitting a bug report:

Check existing issues to avoid duplicates
Use the bug report template
Include: - AxisPy version - Python version - Operating system - Steps to reproduce - Expected vs actual behavior - Error messages and stack traces

Suggesting Features

Open a GitHub Discussion or Feature Request issue
Describe the feature and its use case
Explain why it would be useful to most users

Submitting Pull Requests

Create a new branch from main:

git checkout -b feature/your-feature-name

Make your changes
Write or update tests as needed
Run the full test suite:

pytest tests/

Commit your changes (see `Commit Conventions`_)
Push to your fork:

git push origin feature/your-feature-name

Open a Pull Request on GitHub

Code Standards

Style Guide

Follow PEP 8 for Python code style
Use meaningful variable and function names
Add docstrings to all public functions and classes (Google style)
Maximum line length: 100 characters
Use type hints where appropriate

Testing

Write unit tests for all new functionality
Maintain test coverage above 80%
Tests should be placed in the tests/ directory
Use pytest for testing
Run tests before submitting PR:

pytest tests/ --cov=core --cov=editor --cov=plugins

Commit & Branch Conventions

Branch Naming

Use prefixes to categorize branches:

feature/ - New features (e.g., feature/physics-2d)
fix/ - Bug fixes (e.g., fix/camera-crash)
docs/ - Documentation changes (e.g., docs/api-reference)
refactor/ - Code refactoring (e.g., refactor/input-system)
test/ - Test additions or fixes (e.g., test/animation-coverage)

Commit Messages

We follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types:

feat - New feature
fix - Bug fix
docs - Documentation changes
style - Formatting (no code change)
refactor - Code restructuring
test - Adding or updating tests
chore - Maintenance tasks

Examples:

feat(ai): add GPT-4o provider support
fix(camera): resolve clipping issue at boundaries
docs(tutorials): add multiplayer setup guide

Pull Request Process

What Makes a Good PR

Clear description of changes
Reference to related issue(s)
Screenshots/GIFs for UI changes
Updated documentation if needed
Passing CI/CD checks
Code review approval from at least one maintainer

Review Process

Automated checks must pass (linting, tests)
Code review by maintainers
Address feedback promptly
Once approved, maintainers will merge

Issue Tracking

Labels

We use labels to categorize issues:

bug - Something isn’t working
enhancement - New feature requests
documentation - Documentation improvements
good first issue - Good for newcomers
help wanted - Community assistance needed
priority:high - Urgent issues

Claiming Issues

Comment on an issue to express interest
Wait for assignment before starting work
If inactive for 2+ weeks, the issue may be reassigned

Code of Conduct

This project adheres to the Code of Conduct. By participating, you are expected to uphold this code.

Community & Communication

GitHub Issues: Bug reports and feature requests
GitHub Discussions: General questions and ideas
Response time: Maintainers aim to respond within 48 hours

Legal

License

By contributing, you agree that your contributions will be licensed under the same license as the project (see LICENSE file).

Developer Certificate of Origin

We require all contributors to agree to the Developer Certificate of Origin (DCO) for their contributions. By submitting a PR, you certify that:

You have the right to submit the contribution
The contribution is your original work
You understand the contribution is public

Questions?

If you have questions not covered by this guide, please:

Check existing documentation
Search closed issues on GitHub
Open a new GitHub Discussion

Thank you for contributing to AxisPy Engine!