Devour/CONTRIBUTING.md

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

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

Optional sanity check:

./devour --help

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

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:

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.