# Contributing to Marchwarden

## Workflow

- **Always branch** — never commit directly to `main`
- **Branch naming**: `feat/`, `fix/`, `refactor/`, `chore/` + description (e.g., `feat/tavily-integration`)
- **One branch, one concern** — don't mix unrelated changes
- **Atomic commits** — each commit is one logical unit; write clear messages
- **Tests required** — all code changes to testable modules must include or update tests
- **Test before PR** — run `pytest tests/` and ensure all pass

## Branching

```bash
# Create a feature branch
git checkout -b feat/your-feature-name

# Commit logically
git commit -m "Implement X because Y"

# Push
git push origin feat/your-feature-name
```

## Testing

```bash
# Run all tests
pytest tests/

# Run with coverage
pytest --cov=. tests/

# Run a specific test
pytest tests/test_something.py::test_name
```

## MCP Contract

Before implementing, read [ResearchContract.md](docs/wiki/ResearchContract.md). The `research()` tool signature is the contract; changes require approval.

## PR process

1. Push your branch
2. Create a PR on Forgejo
3. Ensure CI passes (tests, linting)
4. Request review
5. Merge via Forgejo API/UI (not locally)
6. Delete the remote branch
7. Sync local `main`: `git checkout main && git pull --ff-only`

## Questions?

Check the wiki or open an issue.