Contributing to ChatrixCD
Thank you for your interest in contributing to ChatrixCD!
How to Contribute
Reporting Bugs
- Check existing issues
- Create a new issue with:
- Clear title
- Detailed description
- Steps to reproduce
- Expected vs actual behavior
- Environment details
Suggesting Features
- Check existing feature requests
- Open a new issue with:
- Feature description
- Use cases
- Possible implementation approach
Pull Requests
- Fork the repository
- Create a feature branch:
git checkout -b feature/your-feature
- Make your changes
- Add tests if applicable
- Update documentation
- Commit with clear messages
- Push to your fork
- Open a pull request
Development Setup
Prerequisites
- Python 3.9+
- Git
- Virtual environment tool (venv or uv)
Setup Steps
# Clone your fork
git clone https://github.com/YOUR_USERNAME/ChatrixCD.git
cd ChatrixCD
# Create virtual environment
python -m venv .venv
source .venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Install in development mode
pip install -e .
Running Tests
# Run all tests
python -m unittest discover -s tests -v
# Run specific test file
python -m unittest tests.test_config -v
# Run specific test
python -m unittest tests.test_auth.TestMatrixAuth.test_init_password_auth -v
Coding Standards
Python Style
- Follow PEP 8
- Maximum line length: 100 characters
- Use type hints
- Add docstrings to public functions
Code Example
def function_name(param1: str, param2: int) -> bool:
"""Brief description of function.
Args:
param1: Description of param1
param2: Description of param2
Returns:
Description of return value
"""
# Implementation
return True
Commit Messages
- Use present tense: “Add feature” not “Added feature”
- Use imperative mood: “Move cursor to…” not “Moves cursor to…”
- Limit first line to 72 characters
- Reference issues: “Fixes #123”
Branch Naming
feature/description
- New featuresfix/description
- Bug fixesdocs/description
- Documentationrefactor/description
- Code refactoring
Pull Request Process
- Update CHANGELOG.md under “Unreleased” section
- Update documentation if needed
- Ensure all tests pass
- Request review from maintainers
- Address review feedback
- Wait for approval and merge
PR Checklist
- Code follows style guidelines
- Self-review completed
- Comments added for complex code
- Documentation updated
- Tests added/updated
- All tests pass
- CHANGELOG.md updated
- No new warnings
- Branding guidelines followed (if visual changes)
Testing Guidelines
Unit Tests
- Write tests for new functions
- Place in
tests/
directory - Name files
test_<module_name>.py
- Use descriptive test names
Test Coverage
Current coverage goals:
- Config: 95%
- Auth: 80%
- Semaphore: 70%
- Bot: 40%
Branding Guidelines
ChatrixCD maintains consistent visual branding. When contributing visual elements:
Brand Colors
- ChatrixCD Green:
#4A9B7F
(primary) - Dark Background:
#2D3238
- White:
#FFFFFF
Logo Usage
- Use approved logos from
assets/
directory - Follow placement and sizing guidelines
- Don’t modify or distort logos
See BRANDING.md for complete guidelines.
Documentation
Types of Documentation
- Code Documentation: Docstrings
- User Documentation: README, INSTALL, QUICKSTART
- Developer Documentation: ARCHITECTURE, CONTRIBUTING
- Brand Documentation: BRANDING (visual identity)
- API Documentation: Docstrings
Documentation Updates
Update relevant docs when making changes:
- README.md - Overview and features
- INSTALL.md - Installation steps
- QUICKSTART.md - Getting started
- ARCHITECTURE.md - Technical details
- CHANGELOG.md - Change history
Project Structure
ChatrixCD/
├── .github/ # GitHub-specific files
│ ├── ISSUE_TEMPLATE/ # Issue templates
│ └── workflows/ # GitHub Actions
├── chatrixcd/ # Main package
│ ├── __init__.py
│ ├── main.py # Entry point
│ ├── bot.py # Bot core
│ ├── auth.py # Authentication
│ ├── config.py # Configuration
│ ├── commands.py # Commands
│ └── semaphore.py # Semaphore client
├── tests/ # Test suite
├── docs/ # Documentation
└── README.md
Getting Help
Code of Conduct
This project follows the Contributor Covenant Code of Conduct.
License
By contributing, you agree that your contributions will be licensed under the GNU GPL v3.0.
Recognition
Contributors are recognized in:
- CHANGELOG.md
- GitHub contributors page
- Release notes
Thank you for contributing to ChatrixCD! 🚀