# Contributing to Clew Engine

Thank you for your interest in contributing to Clew Engine! We aim to build a piece of software that is not only functional but also a joy to read and maintain. To that end, we adhere strictly to **Clean Code** principles, **12-Factor App** methodology, and **Gang of Four (GoF)** design patterns.

## 🏗 Architectural Philisophy

Clew Engine is a distributed system composed of loosely coupled microservices. Each package (`packages/*`) is designed to be:

1.  **Independently Deployable**: Contains its own `Dockerfile` and `pyproject.toml`.
2.  **12-Factor Compliant**: Configuration via environment variables, stateless processes, and logs as event streams.
3.  **Sovereign**: Data ownership is paramount. We do not lock users into a specific backend.

## 📐 Coding Standards

We are pedantic about design. Please ensure your contributions adhere to the following:

### 1. SOLID Principles
- **SRP**: Classes should have one reason to change.
- **OCP**: Open for extension, closed for modification. Use polymorphism (Strategy Pattern) instead of `if/else` chains for type handling.
- **LSP**: Subclasses must be substitutable for their base classes.
- **ISP**: Many client-specific interfaces are better than one general-purpose interface.
- **DIP**: Depend on abstractions, not concretions. Use Dependency Injection.

### 2. Design Patterns (GoF)
We explicitly use and name our patterns.
- **Factory**: Use for object creation (e.g., `get_vector_store()`).
- **Strategy**: Use for interchangeable algorithms (e.g., `Neo4jStore` vs `NoOpGraphStore`).
- **Adapter**: Use to interface with 3rd party libraries (e.g., `Qdrant` client wrappers).
- **Observer**: Use for event handling (if applicable).

### 3. Clean Code
- **Meaningful Names**: Variables `d`, `temp`, `data` are forbidden. Use `days_since_creation`, `user_record`, etc.
- **Small Functions**: Functions should do one thing and be short.
- **No Side Effects**: Functions should not secretly change state.

## 🛠 Development Workflow

1.  **Fork & Clone**
2.  **Environment Setup**:
    ```bash
    cp .env.example .env
    docker-compose up -d
    ```
3.  **Branching**: Use descriptive feature branches (e.g., `feature/add-redis-cache`, `fix/graph-traversal-bug`).
4.  **Testing**:
    - Every new feature MUST have a test.
    - Run tests with `pytest`.
    - Ensure `mypy` passes (strict typing).

## 📝 Pull Request Process

1.  **Descriptive Title**: "Fix bug" is bad. "Fix NPE in Graph Traversal during cyclic dependency" is good.
2.  **Design Rationale**: Explain *why* you chose a specific pattern. "I used the Strategy pattern here to allow for future graph backends."
3.  **Checklist**:
    - [ ] Tests added/passed
    - [ ] Documentation updated
    - [ ] Linter/Types pass
    - [ ] Design patterns identified

## 📄 License

Clew Engine is licensed under [AGPL-3.0](LICENSE). By submitting a contribution (pull request, patch, or otherwise), you agree that:

1. Your contribution is licensed under **AGPL-3.0**, consistent with the project license.
2. You have the right to submit the contribution under these terms.
3. Any derivative work that incorporates your contribution and is deployed as a **network service** must make its complete source code available to users of that service, per the AGPL-3.0 terms.

If AGPL-3.0 does not meet your needs, a commercial license is available. See [LICENSING.md](LICENSING.md) or contact **matt@matchdav.io**.

## 🔐 Maintainer Guide

### Required Secrets

To enable the CI/CD pipeline, the following secrets must be configured in the repository settings:

| Secret | Description |
| :--- | :--- |
| `PYPI_API_TOKEN` | Token for publishing to PyPI (configured in `release.yml`) |
| `DOCKER_PASSWORD` | Token/Password for Docker Hub or GitHub Container Registry (if applicable) |
| `CLEW_API_KEY` | (Optional) API key for the managed Clew Platform, used for PR analysis on the main repo |
| `CODECOV_TOKEN` | Token for Codecov (required for private repos or to avoid silent failures) |

### Release Process

1.  **Draft Release**: Update `CHANGELOG.md` to move `[unreleased]` changes to a new version section (e.g., `[0.1.0]`).
2.  **Tag**: Create and push a new tag matching the version (e.g., `v0.1.0`).
    ```bash
    git tag v0.1.0
    git push origin v0.1.0
    ```
3.  **Automation**: The `release.yml` workflow will automatically:
    - Build CLI binaries for Linux and macOS.
    - Publish the package to PyPI.
    - Build and push Docker images.
    - Create a GitHub Release with artifacts.

---

Thank you for helping us make Clew Engine a world-class open-source project!
