pyr0ball
df63ffa846
Bookmark is fully open source (donated to Books in Hand nonprofit, no BSL tiering). Adds an MIT LICENSE file, a CONTRIBUTING.md scoped to an early-stage volunteer project, and a PEP 639 license field in pyproject.toml. Repo description and topics were also updated via the Forgejo API for discoverability.
63 lines
2.4 KiB
Markdown
63 lines
2.4 KiB
Markdown
# Contributing to Bookmark
|
|
|
|
Bookmark is an early-stage, fully open-source tool built for Books in Hand,
|
|
a nonprofit that keeps books out of landfills. It's still scaffolding —
|
|
there's no working end-to-end app yet, so the best contributions right now
|
|
are small, focused, and coordinated first.
|
|
|
|
## Before You Start
|
|
|
|
This project is young enough that priorities can shift quickly. Please open
|
|
an issue (or comment on an existing one) describing what you'd like to work
|
|
on before submitting a large pull request — it avoids duplicated effort and
|
|
makes sure the change fits the current phase of the build.
|
|
|
|
See `CLAUDE.md` (also readable as `AGENTS.md`) in the repo root for full
|
|
architecture and design context, including what's in scope for the current
|
|
phase and what's intentionally deferred.
|
|
|
|
## Ground Rules
|
|
|
|
- **Deterministic where it matters.** Size-bucketing (small/medium/large)
|
|
feeds the nonprofit's tax and 501(c)(3) reporting. It must stay
|
|
geometry/visibility-based — never OCR, ML, or LLM-derived. Don't change
|
|
this without understanding why.
|
|
- **No cloud dependencies in the current phase.** Keep the intake pipeline
|
|
fully local.
|
|
- **Say what the mechanism actually is.** Use precise terms — "LLM",
|
|
"vision-LLM (VLM)", "OCR", "barcode decode" — rather than the generic
|
|
word "AI" in code, comments, docs, or UI copy.
|
|
- **Human review before publish.** Any future LLM/VLM-assisted output
|
|
(e.g. cover text extraction) is a draft for a human to approve, never
|
|
auto-published.
|
|
|
|
## Development Workflow
|
|
|
|
```bash
|
|
python -m venv .venv
|
|
.venv/bin/pip install -e ".[dev]"
|
|
.venv/bin/pytest -v
|
|
```
|
|
|
|
This project follows test-driven development — new modules should ship
|
|
with tests under `tests/` that don't require real camera hardware
|
|
(synthetic frames, mocked `cv2.VideoCapture`, `TestClient` for the API).
|
|
|
|
## Commit Style
|
|
|
|
Conventional-commit-style subjects: `feat:`, `fix:`, `docs:`, `chore:`,
|
|
`test:`, `refactor:`. Keep commits small and focused — one logical change
|
|
per commit.
|
|
|
|
## Submitting Changes
|
|
|
|
1. Fork the repo and create a branch for your change.
|
|
2. Make sure `pytest -v` passes.
|
|
3. Open a pull request describing what changed and why.
|
|
4. Be patient — this is a volunteer-maintained nonprofit project, so review
|
|
may take a few days.
|
|
|
|
## Questions
|
|
|
|
Open an issue — it's the best way to reach the maintainers and keeps
|
|
context visible for future contributors.
|