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

docs: generate the configuration reference from Quarkus config metadata instead of hand-maintaining it

Aperta
  • Qualcosa non va?
#672 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à
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Tranquilla
Stack tecnologico
github-actions, java
Ambito
build-system, documentation

Direzione di ricerca

Start with config/ThrillhouseConfig.java and application.properties to see how the @ConfigMapping options and their defaults are declared, then find the hand-written config table in the README. Check how the Quarkus config-doc extension is wired into the Maven build. Done means a generated reference is produced at build time, the README links to it, and a CI check fails when the committed reference is stale. The output format (markdown or asciidoc) is still open and should be settled first.

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

Descrizione

documentation enhancement
Problem Statement

The README's environment-variable/config table (~60 rows) is hand-maintained, separately from the @ConfigMapping interfaces in config/ThrillhouseConfig.java and the defaults in application.properties. Every new option is a three-place change, and the table can silently drift from reality — a growing risk as the pipeline roadmap (#669) adds feature gates (REVIEW_DIMENSION_ROUTING_ENABLED, REVIEW_INCREMENTAL_ENABLED, per-model capability flags in #670, …).

Proposed Solution

Generate the config reference from the config metadata Quarkus already produces for @ConfigMapping types (the same quarkus-config-doc machinery that powers extension docs):

  • Emit a generated markdown (or asciidoc) config-reference file during the build, with property name, env-var form, type, default, and the javadoc description.
  • Replace the README's hand-written table with a short curated "most important settings" section linking to the generated full reference.
  • Add a CI check that fails when the generated reference is stale relative to the committed one (or generate it in the docs workflow so it can never be stale).

Descriptions live in one place — the config interface javadoc — and the docs can no longer disagree with the code.

Alternatives Considered
  • Keep hand-maintaining the table — every config addition remains a multi-place change with silent-drift risk.
  • Doc-only lint that greps for missing keys — catches absence but not wrong defaults/descriptions.
Priority

Nice to have (but pays for itself as the config surface grows through the #669 phases)

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.