# Contributing

> Dev setup (`pip install -e ".[dev]"`), test/lint/type-check commands, pre-commit hooks, branch naming, coverage expectations, CI workflow gates, and documentation update requirements for user-facing changes.

- Repository: EliaszDev/hermes-okf
- GitHub: https://github.com/EliaszDev/hermes-okf
- Human docs: https://grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02
- Complete Markdown: https://grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/llms-full.txt

## Source Files

- `CONTRIBUTING.md`
- `pyproject.toml`
- `.github/workflows/ci.yml`
- `.pre-commit-config.yaml`
- `tests/__init__.py`
- `docs/ARCHITECTURE.md`

---

---
title: "Contributing"
description: "Dev setup (`pip install -e \".[dev]\"`), test/lint/type-check commands, pre-commit hooks, branch naming, coverage expectations, CI workflow gates, and documentation update requirements for user-facing changes."
---

Contributions to **hermes-okf** run through an editable install with the `[dev]` extra, a four-tool quality stack (`black`, `ruff`, `mypy`, `pytest`), optional pre-commit hooks, and a GitHub Actions pipeline that gates merges to `main` on lint, type-check, tests, and OKF bundle validation. The package targets Python 3.9+ and keeps the core runtime lean (`pyyaml` only); development dependencies are isolated in `pyproject.toml` under `[project.optional-dependencies].dev`.

<Note>
By contributing, you agree that your contributions are licensed under the MIT License.
</Note>

## Prerequisites

| Requirement | Detail |
|-------------|--------|
| Python | `>=3.9` per `pyproject.toml` (`requires-python`) |
| Git | Fork/clone workflow against `EliaszDev/hermes-okf` |
| Package manager | `pip` (CI and docs use `pip install -e ".[dev]"`) |

The `[dev]` extra installs `pytest`, `pytest-cov`, `black`, `ruff`, `mypy`, `pre-commit`, and `types-PyYAML`. Install RAG extras separately with `pip install -e ".[rag]"` when working on vector retrieval features.

## Development setup

<Steps>
<Step title="Fork and clone">

Fork the repository on GitHub, then clone your fork:

```bash
git clone https://github.com/YOUR_USERNAME/hermes-okf.git
cd hermes-okf
```

</Step>

<Step title="Install in editable mode">

```bash
pip install -e ".[dev]"
```

This registers console scripts (`hermes-okf`, `hermes-okf-install`, `hermes-okf-uninstall`) and exposes the `hermes_okf` package from `src/hermes_okf`.

</Step>

<Step title="Verify the install">

```bash
pytest --version
hermes-okf --version
```

</Step>
</Steps>

For end-user install paths and optional extras (`[rag]`, `[all]`), see the [Installation](/installation) page.

## Branch naming

| Branch type | Pattern | Notes |
|-------------|---------|-------|
| Main | `main` | Always deployable; CI runs on push and PRs targeting `main` |
| Features | `feature/your-feature-name` | New functionality |
| Bug fixes | `fix/issue-description` | Targeted repairs |

Create feature or fix branches from `main`, keep changes focused, and open pull requests back into `main`.

## Code quality tools

All four tools below run in CI. Run them locally before opening a PR.

### Formatter — black

<ParamField body="line-length" type="number" default="100">
Configured in `[tool.black]`; targets Python 3.9 syntax.
</ParamField>

```bash
# Format
black src tests

# CI-equivalent check
black --check src tests
```

### Linter — ruff

Ruff selects rules `E`, `F`, `I`, `N`, `W`, `UP`, `B`, `C4`, `SIM` and ignores `E501` (line length handled by black).

```bash
ruff check src tests
```

### Type checker — mypy

Mypy runs in **strict** mode on `src/` only (`ignore_missing_imports = true`).

```bash
mypy src
```

### Tests — pytest

Local `pytest` inherits coverage options from `pyproject.toml`:

```bash
pytest
```

Equivalent to:

```bash
pytest --cov=hermes_okf --cov-report=term-missing --cov-report=xml
```

CI overrides `addopts` to avoid double-reporting:

```bash
pytest -o addopts="" --cov=hermes_okf --cov-report=xml
```

## Pre-commit hooks

Pre-commit is encouraged but not required for local work. The repo ships `.pre-commit-config.yaml` with three hooks:

| Hook | Repo pin | Behavior |
|------|----------|----------|
| `black` | `24.4.2` | Auto-format |
| `ruff` | `v0.4.7` | Lint with `--fix`; exits non-zero if fixes were applied |
| `mypy` | `v1.10.0` | Strict check on staged files; includes `types-PyYAML` |

<Steps>
<Step title="Install pre-commit">

```bash
pip install pre-commit   # also included in [dev]
pre-commit install
```

</Step>

<Step title="Run on all files">

```bash
pre-commit run --all-files
```

</Step>
</Steps>

<Tip>
Pre-commit `ruff` uses `--fix`, while CI runs `ruff check` without auto-fix. Run `black --check` locally to match CI exactly.
</Tip>

## Writing tests

Tests live under `tests/` and follow pytest discovery rules from `[tool.pytest.ini_options]`:

- Files: `test_*.py`
- Classes: `Test*`
- Functions: `test_*`

Current modules include `test_bundle.py`, `test_validators.py`, `test_search.py`, `test_graph.py`, `test_memory.py`, `test_agent.py`, `test_hermes.py`, and `test_hermes_integration.py`.

### Filesystem isolation

Use `tempfile.TemporaryDirectory` for bundle and filesystem tests so each case gets a clean OKF root:

```python
import tempfile
from hermes_okf.bundle import OKFBundle

def test_creates_bundle_structure():
    with tempfile.TemporaryDirectory() as tmp:
        bundle = OKFBundle(tmp)
        assert (bundle.root / "index.md").exists()
```

### Coverage expectations

| Scope | Expectation |
|-------|-------------|
| New code | Aim for **>80%** coverage on additions |
| CI enforcement | No `fail_under` threshold; coverage is collected and reported |
| Local default | `--cov=hermes_okf --cov-report=term-missing` via `addopts` |
| CI upload | Codecov receives `coverage.xml` from Python **3.12** only (`fail_ci_if_error: false`) |

Add tests alongside the module you change. For OKF conformance rules exercised by `hermes-okf validate`, see [OKF validation reference](/okf-validation-reference).

## CI workflow gates

The `.github/workflows/ci.yml` workflow triggers on:

- `push` to `main`
- `pull_request` targeting `main`
- `workflow_dispatch` (optional tag input for publish)

```mermaid
flowchart TB
  subgraph triggers["Triggers"]
    push["push → main"]
    pr["PR → main"]
    dispatch["workflow_dispatch"]
  end

  subgraph test_job["job: test"]
    matrix["Python 3.9–3.13 matrix"]
    ruff["ruff check src tests"]
    black["black --check src tests"]
    mypy["mypy src"]
    pytest["pytest + coverage.xml"]
    codecov["codecov upload (3.12 only)"]
    matrix --> ruff --> black --> mypy --> pytest --> codecov
  end

  subgraph validate_job["job: validate-okf"]
    init["hermes-okf init examples/example_bundle"]
    validate["hermes-okf validate --path examples/example_bundle"]
    init --> validate
  end

  subgraph publish_job["job: publish"]
    gate["needs: test + validate-okf success"]
    pypi["PyPI publish if version new"]
    gate --> pypi
  end

  triggers --> test_job
  triggers --> validate_job
  test_job --> publish_job
  validate_job --> publish_job
```

### `test` job

| Step | Command | Gate |
|------|---------|------|
| Install | `pip install -e ".[dev]"` + `types-PyYAML` | Must succeed |
| Lint | `ruff check src tests` | Must pass |
| Format | `black --check src tests` | Must pass |
| Types | `mypy src` | Must pass |
| Tests | `pytest -o addopts="" --cov=hermes_okf --cov-report=xml` | Must pass |

Runs across Python **3.9, 3.10, 3.11, 3.12, and 3.13** on `ubuntu-latest`.

### `validate-okf` job

Exercises the standalone CLI against a freshly initialized bundle:

```bash
hermes-okf init examples/example_bundle
hermes-okf validate --path examples/example_bundle
```

This job runs on Python 3.12 and must pass before publish.

### `publish` job

Runs only when:

- `test` and `validate-okf` both succeed, **and**
- Event is `push` to `main` **or** `workflow_dispatch`

Publish skips if the version in `src/hermes_okf/__init__.py` already exists on PyPI.

<Warning>
A green local `pytest` run does not replace CI. Always run `black --check`, `ruff check`, and `mypy src` before pushing—CI failures on formatting have shipped in past releases.
</Warning>

## Documentation requirements

Update docs when your change affects users or architecture:

| Change type | Update |
|-------------|--------|
| User-facing behavior, CLI flags, install steps | `README.md` |
| Design, module responsibilities, layer boundaries | `docs/ARCHITECTURE.md` |
| New integration surfaces or workflows | `examples/` (e.g. `basic_usage.py`, `full_agent.py`, `rag_integration.py`) |

`CONTRIBUTING.md` is the canonical short guide; this wiki page expands CI and tooling detail.

For layered module ownership when editing `docs/ARCHITECTURE.md`, the stack spans CLI surfaces, Hermes plugin layer, universal provider, core OKF layer, and filesystem persistence—see [Overview](/overview) for runtime assumptions.

## Submitting a pull request

<Steps>
<Step title="Run the local gate suite">

```bash
pytest
ruff check src tests && black --check src tests
mypy src
```

</Step>

<Step title="Push your branch and open a PR to main">

Write a description that explains **why** and **what**. Link related GitHub issues.

</Step>

<Step title="Wait for CI">

All matrix Python versions, `validate-okf`, and lint/type jobs must pass.

</Step>
</Steps>

### PR checklist

- [ ] Tests pass (`pytest`)
- [ ] Lint passes (`ruff check src tests`)
- [ ] Format passes (`black --check src tests`)
- [ ] Types pass (`mypy src`)
- [ ] User-facing docs updated (`README.md`, `examples/` as needed)
- [ ] Architecture docs updated for design changes (`docs/ARCHITECTURE.md`)
- [ ] New code has tests; coverage target >80% on additions

## Community

- **Bugs and feature requests**: Open a GitHub issue (templates under `.github/ISSUE_TEMPLATE/`)
- **Architectural proposals**: Start a discussion before large refactors
- **Questions**: Use issues with environment details (OS, Python version, `hermes-okf` version)

## Related pages

<CardGroup>
<Card title="Installation" href="/installation">
PyPI install targets, optional extras, and entry-point scripts for local and production environments.
</Card>
<Card title="Overview" href="/overview">
Exposed surfaces (standalone CLI, Hermes plugin, Python SDK) and the shortest path from install to first memory write.
</Card>
<Card title="OKF validation reference" href="/okf-validation-reference">
Rules enforced by `OKFValidator` and the `hermes-okf validate` command—directly exercised in CI.
</Card>
<Card title="Troubleshooting" href="/troubleshooting">
Recovery steps when install scripts, plugin discovery, or bundle paths fail during development.
</Card>
</CardGroup>