Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open
  • Is something wrong?
#672 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
github-actions, java
Domain
build-system, documentation

Research direction

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.

Written by the indexing model from the issue text.

Description

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)

Dominant language
Java
Stars
35
Forks
7
Avg merge
9h 23m
Merged PRs (30d)
154

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from devops-thiago/ThrillhouseBot

All issues in devops-thiago/ThrillhouseBot

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.