Improve Documentation for YAML and CLI Options
Maintainers usually reply within 2 days
@OdenTakashi is already working on this.
Since Apr 5, 2026.
Assessment
This issue has not been assessed yet.
Description
Thanks for taking care of the maintenance. 🚀
Background
Currently, the README documents only the configuration options that can be passed via the CLI.
However, there are additional options defined in the YAML configuration file that cannot be configured through the CLI, and these options are not comprehensively documented.
Problem
This results in a discoverability issue:
- Some options are available only via YAML and are not mentioned in the README.
- Newly added YAML-only options are difficult to notice.
- Existing options may be unintentionally overlooked.
- This may lead to duplicate or redundant feature proposals.
For example, the ignore_multi_database_name option can be configured via YAML, but it is not documented in the README.
Because it was not easily discoverable, a PR was submitted proposing a similar new option: https://github.com/drwl/annotaterb/pull/291#issuecomment-3497296456
Proposal
To improve clarity and prevent confusion, I propose adding a comprehensive list of all available configuration options to the README — including both CLI and YAML options.
Possible Idea
As a possible idea, we could introduce a single Markdown table summarizing all options in one place.
Example:
| YAML Option | CLI Option | Default | Description |
|---|---|---|---|
| include_version | --show-migration | false | Adds the current migration version to the annotation |
This approach would:
- Improve discoverability
- Make configuration options easier to understand
- Reduce the likelihood of duplicate feature proposals
- Provide a clear reference for contributors and users
If there are other suggestions or better ways to organize this, I’d be happy to hear them.
Expected Outcome
By documenting all configuration options in a structured and centralized format, the project will become:
- More transparent
- Easier to contribute to
- Less prone to confusion regarding existing functionality
- Dominant language
- Ruby
- Stars
- 624
- Forks
- 95
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 10
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from drwl/annotaterb
-
additional_file_patterns no longer matches files outside empty root_dirPossibly taken @Shaisolaris claimed this 3 days ago. Openbug
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
drwl/annotaterb#406 ·
Maintainers usually reply within 2 days
-
`v4.25.0`: enum columns declared with a Rails-side `default:` still annotate the raw value instead of the labelPossibly taken @xanagi claimed this 3 days ago. Open
Difficulty 3/5 Half a day Newbie friendliness 62/100
drwl/annotaterb#408 ·
Maintainers usually reply within 2 days
-
Difficulty 5/5 Over a week Newbie friendliness 25/100
drwl/annotaterb#369 · 1 reaction ·
Maintainers usually reply within 2 days
-
`annotaterb models --delete` doesn't remove annotations from files excluded via `exclude_*`Possibly taken A pull request linked to this issue is open or already merged. Open
Difficulty 3/5 1-2 days Newbie friendliness 65/100
drwl/annotaterb#340 · 2 comments · 1 reaction ·
Maintainers usually reply within 2 days
-
Difficulty 4/5 3-5 days Newbie friendliness 35/100
drwl/annotaterb#323 · 1 comment ·
Maintainers usually reply within 2 days
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 66/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
:bank: debt
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
cucumber/cucumber-ruby-core#346 · 1 comment ·
-
Difficulty 1/5 Under an hour Newbie friendliness 75/100
TheOdinProject/curriculum#31467 · 2 comments ·
Maintainers usually reply within 1 day
-
message-patterns
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
sisimai/rb-sisimai#468 ·