mirror of
https://github.com/Dvorinka/Devour.git
synced 2026-06-03 20:13:03 +00:00
Tomas Dvorak
118 lines
3.1 KiB
Markdown
118 lines
3.1 KiB
Markdown
# 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.
|