# Contributing to Devour

Thanks for considering a contribution.

Devour is moving fast, and practical contributions (bug fixes, docs cleanup, tests, stability work) are especially valuable right now.

## Before You Start

- Check existing issues/PRs to avoid duplicate work.
- If the change is non-trivial, open an issue first to align on direction.
- Keep PRs focused. Small, reviewable changes get merged faster.

## Local Setup

```bash
git clone <your-fork-or-repo-url>
cd devour
go mod download
go build -o devour ./cmd/devour
```

Optional sanity check:

```bash
./devour --help
```

For quality/review commands, install the delegated upstream tool first:

```bash
pip install --upgrade "desloppify[full]"
```

## Branch and Commit Workflow

1. Fork the repo.
2. Create a branch from `main`:
   `git checkout -b feat/short-description`
3. Make your changes.
4. Run tests/checks.
5. Commit with a clear message.
6. Open a PR.

Commit style suggestion:

- `feat: add xyz`
- `fix: resolve panic in abc`
- `docs: clarify quick start`
- `test: add coverage for module`

## What To Test

At minimum, run:

```bash
go test ./...
```

If your changes affect CLI behavior, also run relevant commands directly (for example `devour get`, `devour ask`, `devour quality scan --path .`, `devour review --prepare`).

If you touch docs, verify commands and paths are real.

## Current Known Limitations

Please keep these in mind when proposing fixes or documentation:

- Remote workflows are still experimental:
  - `devour serve --remote` is available, but local stdio JSON-RPC is the primary stable mode.
  - remote `push` flows are intentionally disabled in stable behavior.
- Live scraping quality can vary with upstream site changes; use `devour verify smoke` before releases.
- Language support is broad, but extraction quality differs by source type and site structure.
- Quality analyzers are strongest for Go code; cross-language analysis remains limited.

PRs that improve these areas are highly appreciated.

## Pull Request Checklist

Before opening a PR, confirm:

- [ ] Change is scoped and clearly described.
- [ ] Tests pass locally (`go test ./...`).
- [ ] New behavior includes tests when feasible.
- [ ] Docs updated for user-facing changes.
- [ ] No unrelated refactors mixed in.

## Coding Guidelines

- Follow existing Go style in the touched package.
- Prefer clear, simple control flow over clever abstractions.
- Add comments only when they explain non-obvious intent.
- Preserve current CLI UX unless there is a strong reason to change it.

## Reporting Bugs

When filing a bug, include:

- Devour command used
- exact error output
- OS and Go version
- minimal reproduction steps

Bug reports with reproducible steps are fixed much faster.

## Documentation Contributions

Docs improvements are first-class contributions.

Useful docs PRs include:

- fixing incorrect command examples
- clarifying status of in-progress features
- adding troubleshooting notes
- improving onboarding for first-time contributors

## Questions

If something is unclear, open an issue and ask directly. It is better to align early than rework a large PR later.