250
CONTRIBUTING.md
Archivo normal
250
CONTRIBUTING.md
Archivo normal
@@ -0,0 +1,250 @@
|
||||
# Contributing to Debai
|
||||
|
||||
Thank you for your interest in contributing to Debai! This document provides guidelines and instructions for contributing.
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
By participating in this project, you agree to maintain a respectful and inclusive environment for everyone.
|
||||
|
||||
## How to Contribute
|
||||
|
||||
### Reporting Bugs
|
||||
|
||||
1. Check if the bug has already been reported in [Issues](https://github.com/debai/debai/issues)
|
||||
2. If not, create a new issue with:
|
||||
- Clear, descriptive title
|
||||
- Steps to reproduce
|
||||
- Expected vs actual behavior
|
||||
- System information (OS, Python version, etc.)
|
||||
- Relevant logs or screenshots
|
||||
|
||||
### Suggesting Features
|
||||
|
||||
1. Check existing issues and discussions for similar suggestions
|
||||
2. Create a new issue with:
|
||||
- Clear description of the feature
|
||||
- Use cases and benefits
|
||||
- Possible implementation approach
|
||||
|
||||
### Submitting Code
|
||||
|
||||
1. **Fork** the repository
|
||||
2. **Create a branch** for your changes:
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
3. **Make your changes** following our coding standards
|
||||
4. **Write tests** for new functionality
|
||||
5. **Run tests** to ensure everything passes:
|
||||
```bash
|
||||
pytest tests/
|
||||
```
|
||||
6. **Commit** with clear messages:
|
||||
```bash
|
||||
git commit -m "feat: add new agent template for network monitoring"
|
||||
```
|
||||
7. **Push** to your fork
|
||||
8. **Create a Pull Request**
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Python 3.10 or later
|
||||
- GTK 4.0 and libadwaita 1.0
|
||||
- Docker (for model testing)
|
||||
|
||||
### Setting Up
|
||||
|
||||
```bash
|
||||
# Clone your fork
|
||||
git clone https://github.com/YOUR_USERNAME/debai.git
|
||||
cd debai
|
||||
|
||||
# Create virtual environment
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
|
||||
# Install in development mode
|
||||
pip install -e ".[dev]"
|
||||
|
||||
# Install pre-commit hooks
|
||||
pre-commit install
|
||||
```
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
pytest
|
||||
|
||||
# Run with coverage
|
||||
pytest --cov=debai --cov-report=html
|
||||
|
||||
# Run specific test file
|
||||
pytest tests/test_agent.py
|
||||
|
||||
# Run with verbose output
|
||||
pytest -v
|
||||
```
|
||||
|
||||
### Code Style
|
||||
|
||||
We use the following tools for code quality:
|
||||
|
||||
- **Black** for code formatting
|
||||
- **isort** for import sorting
|
||||
- **Ruff** for linting
|
||||
- **mypy** for type checking
|
||||
|
||||
Run all checks:
|
||||
|
||||
```bash
|
||||
# Format code
|
||||
black src/
|
||||
isort src/
|
||||
|
||||
# Lint
|
||||
ruff check src/
|
||||
|
||||
# Type check
|
||||
mypy src/
|
||||
```
|
||||
|
||||
## Commit Message Convention
|
||||
|
||||
We follow [Conventional Commits](https://www.conventionalcommits.org/):
|
||||
|
||||
```
|
||||
type(scope): description
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer]
|
||||
```
|
||||
|
||||
Types:
|
||||
- `feat`: New feature
|
||||
- `fix`: Bug fix
|
||||
- `docs`: Documentation changes
|
||||
- `style`: Code style changes (formatting)
|
||||
- `refactor`: Code refactoring
|
||||
- `test`: Adding or updating tests
|
||||
- `chore`: Maintenance tasks
|
||||
|
||||
Examples:
|
||||
```
|
||||
feat(agent): add support for scheduled tasks
|
||||
fix(gui): resolve memory leak in agent list
|
||||
docs: update installation instructions
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
debai/
|
||||
├── src/debai/ # Main package
|
||||
│ ├── core/ # Core business logic
|
||||
│ │ ├── agent.py # Agent management
|
||||
│ │ ├── model.py # Model management
|
||||
│ │ ├── task.py # Task management
|
||||
│ │ └── system.py # System utilities
|
||||
│ ├── cli/ # Command-line interface
|
||||
│ ├── gui/ # GTK4 graphical interface
|
||||
│ └── generators/ # Image generators
|
||||
├── tests/ # Test suite
|
||||
├── docs/ # Documentation
|
||||
├── data/ # Data files and resources
|
||||
└── debian/ # Debian packaging
|
||||
```
|
||||
|
||||
## Testing Guidelines
|
||||
|
||||
1. Write tests for all new functionality
|
||||
2. Maintain or improve code coverage
|
||||
3. Use meaningful test names
|
||||
4. Group related tests in classes
|
||||
5. Use fixtures for common setup
|
||||
|
||||
Example test:
|
||||
|
||||
```python
|
||||
import pytest
|
||||
from debai.core.agent import Agent, AgentConfig
|
||||
|
||||
class TestAgent:
|
||||
@pytest.fixture
|
||||
def agent_config(self):
|
||||
return AgentConfig(
|
||||
name="Test Agent",
|
||||
model_id="llama3.2:3b",
|
||||
)
|
||||
|
||||
def test_agent_creation(self, agent_config):
|
||||
agent = Agent(agent_config)
|
||||
assert agent.name == "Test Agent"
|
||||
assert agent.status.value == "stopped"
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_agent_start_stop(self, agent_config):
|
||||
agent = Agent(agent_config)
|
||||
# Test start/stop behavior
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
- Update docstrings for new/modified functions
|
||||
- Use Google-style docstrings
|
||||
- Update README.md for user-facing changes
|
||||
- Add man page entries for new CLI commands
|
||||
|
||||
Example docstring:
|
||||
|
||||
```python
|
||||
def create_agent(config: AgentConfig) -> Agent:
|
||||
"""Create a new AI agent.
|
||||
|
||||
Args:
|
||||
config: Configuration for the agent including name,
|
||||
type, and model settings.
|
||||
|
||||
Returns:
|
||||
The newly created Agent instance.
|
||||
|
||||
Raises:
|
||||
ValueError: If an agent with the same ID already exists.
|
||||
|
||||
Example:
|
||||
>>> config = AgentConfig(name="My Agent", model_id="llama3.2:3b")
|
||||
>>> agent = create_agent(config)
|
||||
"""
|
||||
```
|
||||
|
||||
## Pull Request Process
|
||||
|
||||
1. Ensure all tests pass
|
||||
2. Update documentation as needed
|
||||
3. Add entry to CHANGELOG.md
|
||||
4. Request review from maintainers
|
||||
5. Address review feedback
|
||||
6. Squash commits if requested
|
||||
|
||||
## Release Process
|
||||
|
||||
Maintainers follow this process for releases:
|
||||
|
||||
1. Update version in `pyproject.toml`
|
||||
2. Update CHANGELOG.md
|
||||
3. Create release tag
|
||||
4. Build and publish packages
|
||||
5. Update documentation
|
||||
|
||||
## Getting Help
|
||||
|
||||
- Open an issue for questions
|
||||
- Join discussions on GitHub
|
||||
- Check existing documentation
|
||||
|
||||
## License
|
||||
|
||||
By contributing, you agree that your contributions will be licensed under the GPL-3.0 license.
|
||||
Referencia en una nueva incidencia
Block a user