Contributing

Contributing

Development Setup

1. Clone the repository and set up your environment (see Installation)
2. Install development dependencies: pip install -r requirements-dev.txt
3. Install pre-commit hooks: pre-commit install

Git Workflow

Never commit directly to develop. Always use feature branches.

Create a Feature Branch

git checkout develop
git checkout -b <prefix>/<name>

Branch prefixes:

• feat/ - New features
• fix/ - Bug fixes
• chore/ - Maintenance tasks
• docs/ - Documentation changes

Make Changes

1. Write your code following the project standards (see below)
2. Write tests for new functionality
3. Run the test suite: python3 -m pytest tests/ -v
4. Commit with Conventional Commits format

Commit Messages

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

[optional body]

Examples:

feat(minion): add clarifying questions via Slack
fix(overlord): handle missing Docker socket gracefully
chore(deps): update openai SDK to 1.5.0
docs(wiki): add deployment guide

Merge to Develop

git checkout develop
git merge <branch> --no-ff -m "Merge branch '<branch>' into develop"
git branch -d <branch>
git push nebulus-atom develop

Code Standards

Architecture

• MVC pattern: Models in models/, Views in views/, Controllers in controllers/
• SOLID principles: Single responsibility, dependency injection, composition over inheritance
• Type hints mandatory: All functions and methods must have type annotations
• Async for I/O: Use async/await for I/O operations

Style

• Linter: ruff (enforced via pre-commit)
• Formatter: ruff-format (enforced via pre-commit)
• Data models: Use @dataclass or Pydantic, avoid raw dicts at boundaries
• Private members: _variable prefix, @property for access
• Interfaces: Use abc.ABC and abc.abstractmethod

Testing

• Framework: pytest with pytest-asyncio
• Location: tests/test_<module>.py
• Mock external deps: Don't make real API calls in tests
• Use tmp_path: For tests that need file system access
• Run before committing: python3 -m pytest tests/ -v

What Not to Do

• Don't add features beyond what was requested
• Don't add error handling for impossible scenarios
• Don't create abstractions for one-time operations
• Don't commit .env files or secrets
• Don't skip pre-commit hooks (--no-verify)
• Don't force push to develop

Project Structure

nebulus_atom/     # Core CLI agent
nebulus_swarm/    # Multi-agent swarm system
tests/            # All tests
docs/             # Design documents and feature specs
wiki/             # GitHub Wiki (separate git repo)

Related Pages

• Architecture - System design
• Testing - How to run and write tests
• Configuration - Environment variables