Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
177 lines (125 loc) · 5.47 KB

CONTRIBUTING.md

File metadata and controls

177 lines (125 loc) · 5.47 KB

Contributing to Codomyrmex

Thank you for your interest in contributing to Codomyrmex! This document provides a short entry point.

For the full maintainer guide (environment setup, RASP documentation, AI agent workflows, and detailed testing policy), see .github/CONTRIBUTING.md.

Getting Started

Prerequisites

  • Python 3.11+
  • UV package manager
  • Git

Development Setup

# Clone the repository
git clone https://github.com/docxology/codomyrmex.git
cd codomyrmex

# Install dependencies with UV
uv sync --all-extras --dev

# Run tests to verify setup
uv run pytest

Files not to commit

Never commit local secrets or generated artifacts, even if they appear in your working tree: .env, .encryption_key, memory.db, *.log, coverage.json, cov_config.json, codomyrmex_inventory.json, and similar outputs. They are listed in .gitignore. If something sensitive was ever pushed, rotate credentials and remove it from history per SECURITY.md.

Development Workflow

Branching Strategy

  • main: Stable production code
  • develop: Integration branch for features
  • feature/*: New features
  • fix/*: Bug fixes
  • docs/*: Documentation updates

Making Changes

  1. Create a branch from main:

    git checkout -b feature/your-feature-name

  2. Make your changes following the code style guidelines

  3. Run pre-commit checks:

    uv run pre-commit run --all-files

  4. Run tests:

    uv run pytest src/codomyrmex/tests/unit/ -v

  5. Commit your changes with clear, descriptive messages:

    git commit -m "feat: add new feature description"

Code Style

  • Python: We follow PEP 8 with Ruff formatting
  • Linting: Ruff for linting and formatting (replaces Black + flake8)
  • Type hints: Required for all public functions
  • Docstrings: Google-style docstrings for all modules, classes, and functions

Pre-commit Hooks

We use pre-commit hooks to ensure code quality. Install them with:

uv run pre-commit install

Testing

  • Write tests for all new features
  • Maintain test coverage above the project gate (≥40%, ratcheting upward)
  • Place unit tests in src/codomyrmex/tests/unit/
  • Place integration tests in src/codomyrmex/tests/integration/

Documentation

  • Update relevant documentation when making changes
  • Every module follows the RASP pattern — four standard docs that must stay in sync with code:
    • README.md — Module overview, key exports, quick start
    • AGENTS.md — AI agent coordination and operating contracts
    • SPEC.md — Functional specification and design rationale
    • PAI.md — PAI system integration and algorithm phase mapping
  • Additionally, modules with programmatic APIs maintain API_SPECIFICATION.md and AI-callable tools maintain MCP_TOOL_SPECIFICATION.md
  • See Documentation Guide for detailed writing guidance

Commit Messages

We follow Conventional Commits:

feat: add new feature description
fix: resolve specific bug
docs: update module documentation
refactor: restructure without behavior change
test: add or update tests
chore: maintenance tasks

Pull Requests

  1. Ensure all tests pass
  2. Update documentation as needed (RASP files for affected modules)
  3. Add a clear PR description
  4. Request review from maintainers

Error Handling Convention

Codomyrmex has two distinct error handling patterns depending on the module type:

Shell / subprocess utilities → return dict

Functions that wrap shell commands or subprocesses always return a dict and never raise on process failure (unless an explicit check=True flag is provided). This allows orchestration pipelines to aggregate outcomes without try/except at every call site.

# Shell utility — returns dict
result = shell("my-command")
if not result["success"]:
    logger.error(result["error"])

Standard keys: success (bool), returncode (int|None), stdout, stderr, execution_time (float), and optionally error (str) for timeout/OS errors.

Agent / Python methods → raise typed exceptions

Agent methods and Python-native APIs raise typed exceptions for caller ergonomics. The caller uses try/except and handles the specific error type.

# Agent method — raises on failure
try:
    result = agent.execute(task)
except AgentTimeoutError as e:
    logger.error(f"Agent timed out: {e}")

The rule of thumb: if your function's primary use case is subprocess interop or orchestration pipelines, use the dict pattern. If it's a Python object method called from Python code, use exceptions.

Related Documentation

Document Purpose
README.md Project overview and quick start
SPEC.md Functional specification and design principles
AGENTS.md AI agent coordination and navigation
SECURITY.md Security policies and vulnerability reporting
CODE_OF_CONDUCT.md Community standards
CHANGELOG.md Version history and release notes
Testing Strategy Testing approach and best practices
Environment Setup Development environment configuration

Questions?

Open an issue for questions or discussions about contributing.