Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

docs: document just-in-time abstraction convention in CONTRIBUTING.md

Aperta
  • Qualcosa non va?
#329 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
45/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Ferma
Stack tecnologico
markdown
Ambito
documentation

Direzione di ricerca

Read PLAN.md architecture decision #2 and the relevant examples listed in the issue, then add the convention and review checklist to CONTRIBUTING.md. Link to that section from docs/ARCHITECTURE.md and update decision #2 as specified. Done means the new section is at most about 40 lines and includes the convention, checklist, and an in-repo example, with both links in place.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

documentation enhancement
Problem Statement

PLAN.md architecture decision #2 calls for a reviewable convention: introduce an abstraction only when the second real implementation arrives. This guards ThrillhouseBot's simplicity/DRY goals under feature pressure (competitive parity with PR-Agent, Greptile cross-file context, multi-provider routing, etc.) but the rule is not yet written in CONTRIBUTING.md.

Contributors and reviewers have no shared, linkable standard when debating "should we add an interface now?" — leading to either premature abstraction or ad-hoc pushback in PR threads.

Proposed Solution

Add a short, actionable section to CONTRIBUTING.md (and cross-link from docs/ARCHITECTURE.md if appropriate) covering:

  1. Default: concrete implementation first; duplicate logic twice only when the second use case is real (not speculative).
  2. When to abstract: second distinct implementation with the same seam (e.g. second ContextProvider, second ChatModelProvider — see #30, #55).
  3. When not to abstract: "we might need GitLab someday" (#37), "PR-Agent has 20 tools" — ticket the feature, ship the simplest path.
  4. Review checklist: PR description should call out new interfaces/SPIs and justify why the second implementation exists now or why deferral is safe.
  5. Examples from this repo: ReviewOrchestrator decomposition (#250 — done), §23 AI-invocation contract (ModelSelector / ContextProvider / ReviewStrategy), Qlawkus boundary discipline (cite PLAN.md, not copy module count).

Pair with v0.4.0 config documentation (#50) and hosted docs (#319) so the convention is discoverable outside the repo root.

Related issues
  • #50 — per-model config + config docs (same v0.4.0 docs pass)
  • #319 — GitHub Pages docs site
  • #314 — quarkus-github-app spike (evaluate extension value before abstracting webhook layer)
  • #30 — provider SPI (future second implementation test case)
  • #250 — orchestrator decomposition (positive example)
Acceptance criteria
  • New CONTRIBUTING.md section (≤ ~40 lines) with the convention, review checklist, and at least one in-repo example
  • docs/ARCHITECTURE.md links to the section (one paragraph max — no duplication)
  • PLAN.md architecture decision #2 updated to link the new issue (maintainer doc sync)
  • No code changes required — documentation only
Alternatives considered
  • Issue template checkbox only — too easy to ignore; needs a visible contributor doc.
  • Strict lint/rule — overkill; convention + review culture is enough for OSS.
Priority

Important for v0.4.0 docs polish — low implementation cost, high leverage as the roadmap adds competitive features (#316, #317).

Code of Conduct
  • I have searched for existing issues and this is not a duplicate.
Lingua principale
Java
Stelle
35
Fork
7
Merge medio
9h 23m
PR unite (30g)
154

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di devops-thiago/ThrillhouseBot

Tutte le issue di devops-thiago/ThrillhouseBot

Issue simili

Altre issue su Java

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.