Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
100 lines (75 loc) · 5.18 KB

CONTRIBUTING.md

File metadata and controls

100 lines (75 loc) · 5.18 KB
Raw

Contributing to Queer the Stacks

Thanks for your interest. Queer the Stacks is a self-hosted, single-user reading dashboard and ethical recommender (AGPL-3.0-or-later) for a queer/trans/speculative reading life. It is small on purpose and opinionated about a few invariants (below) that are the whole point of the project — please keep those intact. Everything else is fair game, and first-time contributors are genuinely welcome.

By participating you agree to the Code of Conduct.

The one command that proves it: make verify

make install        # bootstrap .venv on Python 3.14 + install dev/app extras
make verify         # the full local mirror of the CI gate set

make verify runs, in order, lint · typecheck · test (≥85% coverage) · security · a11y · eval — the same checkable gates CI enforces (see .github/workflows/ci.yml). A change is not done until make verify is green locally. CI re-runs the same gates on every PR to main; that check must pass to merge.

Useful individual targets: make format, make lint, make typecheck, make test, make security, make a11y, make eval, make perf, make audit. Run make help for the list. To see the dashboard without a real library, make dev runs it in demo mode (no API key, no data).

Branch model & pull requests

  • main is the released, protected branch. Do not push to it directly.
  • Work on a short-lived branch named for the change (e.g. feat/series-browse, fix/kosync-retry, docs/...). Open a PR into main.
  • Keep a PR to one logical change. Before requesting review:
    • make verify is green locally.
    • Tests are added or updated for the behavior you changed.
    • Docs are updated when behavior or interfaces move; if you touched a responsible-tech control, refresh the relevant note under docs/audits/.
    • No secrets, tokens, or real library data are included in the diff.

Commit messages — Conventional Commits + sign-off

Commits and PR titles follow Conventional Commits 1.0.0 (feat, fix, docs, refactor, test, build, ci, chore, perf, revert), matching the existing history.

Sign off every commit (Developer Certificate of Origin, -s):

git commit -s -m "feat(recommender): surface small-press co-reads"

-s appends the Signed-off-by: trailer matching your git config user.name/user.email. By signing off you certify you wrote the contribution or have the right to submit it under the project's AGPL-3.0-or-later license.

Invariants — do not regress these

These are guardrails, not preferences. A PR that weakens one needs an explicit rationale and will usually be declined:

  • Identity-sourcing, never inference. Books and authors are described only via sourced theme/genre descriptors. Never infer, guess, or auto-assign an author's identity (gender, sexual orientation, etc.). Diverse-shelf analytics are built from sourced descriptors, never inferred author identity — see docs/ethical-book-data-sources.md.
  • No Goodreads / no gatekept catalogs. Recommendations are sourced from OpenLibrary, Hardcover, Bookwyrm, and curated community lists, behind a hard allowlist. Do not scrape Goodreads (Amazon ToS + gatekeeping). Every recommendation must show why + which source.
  • Local-only and private. Reading data never leaves the self-hosted instance: no third-party analytics, no telemetry, no auto-egress (share cards are composed locally and posted only when you copy them). Optional embeddings run local-only. The dashboard serves only behind auth.
  • Read-only against real libraries. Calibre metadata.db and KOReader statistics.sqlite are snapshotted first and opened strictly read-only; ingest must never risk writing to or corrupting the user's real libraries (see docs/audits/library-safety.md).

The corresponding tests and audits under docs/audits/ enforce these; if you change a control, update the audit note in the same PR.

What lives where (so you change the right file)

  • App server / dashboard is under app/; ingest and the stacks CLI under ingest/; the recommender under recommender/; tests under tests/.
  • New catalog adapters go behind the existing allowlist, with provenance on every result — never a raw, unlisted source.
  • Responsible-tech artifacts live under docs/audits/ and are regenerated by make audit (a11y + eval); commit the regenerated artifact when behavior changes.

Security issues

Do not open a public issue for a vulnerability. Follow SECURITY.md for private, coordinated disclosure.

Standards

make verify is the public, self-contained merge gate. Maintainer branches also check the pinned portfolio policy version recorded in .standards-version. GitHub does not expose repository secrets to forks, so external pull requests skip that private policy fetch and must pass the complete local verification command before review.

Maintainer: Chelsea Kelly-Reif · License: AGPL-3.0-or-later.