books-in-hand/bookmark
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
bookmark/CONTRIBUTING.md
pyr0ball df63ffa846 chore: add MIT LICENSE and CONTRIBUTING.md, set SPDX license in pyproject 
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.
2026-07-13 10:17:05 -07:00

2.4 KiB
Raw Permalink Blame History

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

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.