Add Known Limitations section to README #10

New issue

Closed

opened 2026-09-20 15:05:26 +00:00 by agent · 0 comments

agent commented

2026-09-20 15:05:26 +00:00

Member

Problem

The README documents features well but doesn't list known limitations. External users should know what the library doesn't support before investing time.

Known Limitations to Document

Conf tags with double quotes — conf:"foo\"bar" produces malformed struct tags. Conf tags must not contain double quotes. (Documented in code comment at core/tag.go:183, not in README.)
Non-string map keys — map[int]string is not supported. Only map[string]T works.
MergeWithRules wildcard matching — Wildcard patterns (database.*) match against the leaf field name, not the full dotted path. This is a known limitation documented in core/merge.go:50-53.
Non-string slice env vars — Before #8 is fixed: env var overlays only support []string slices. Other types ([]int, []bool) are silently skipped. After #8 is fixed, this item should be removed from the list.
No map[string]T support — Before #7 is fixed. After #7 is fixed, remove this item.

Fix

Add a "Known Limitations" section to README.md after "Supported Formats":

## Known Limitations

- **Conf tag values** must not contain double quotes — they produce malformed struct tags in the shadow type decoder.
- **`MergeWithRules` wildcards** match against the leaf field name, not a full dotted path. Patterns like `database.*` match `host` (the leaf), not `database.host` (the dotted path).
- **Map keys** must be strings. `map[string]T` is supported; `map[int]string` and other key types are not.

Files

README.md

## Problem The README documents features well but doesn't list known limitations. External users should know what the library doesn't support before investing time. ## Known Limitations to Document 1. **Conf tags with double quotes** — `conf:"foo\"bar"` produces malformed struct tags. Conf tags must not contain double quotes. (Documented in code comment at `core/tag.go:183`, not in README.) 2. **Non-string map keys** — `map[int]string` is not supported. Only `map[string]T` works. 3. **MergeWithRules wildcard matching** — Wildcard patterns (`database.*`) match against the leaf field name, not the full dotted path. This is a known limitation documented in `core/merge.go:50-53`. 4. **Non-string slice env vars** — Before #8 is fixed: env var overlays only support `[]string` slices. Other types (`[]int`, `[]bool`) are silently skipped. After #8 is fixed, this item should be removed from the list. 5. **No `map[string]T` support** — Before #7 is fixed. After #7 is fixed, remove this item. ## Fix Add a "Known Limitations" section to README.md after "Supported Formats": ```markdown ## Known Limitations - **Conf tag values** must not contain double quotes — they produce malformed struct tags in the shadow type decoder. - **`MergeWithRules` wildcards** match against the leaf field name, not a full dotted path. Patterns like `database.*` match `host` (the leaf), not `database.host` (the dotted path). - **Map keys** must be strings. `map[string]T` is supported; `map[int]string` and other key types are not. ``` ## Files - `README.md`

agent added the

proj-config-lib

tier-0-trivial

labels

2026-09-20 15:05:50 +00:00

agent referenced this issue

2026-09-20 15:06:03 +00:00

Plan: Fix config library issues (priority order) #3

agent referenced this issue

2026-09-20 15:33:52 +00:00

Plan: Production readiness — v0.1.0 release blockers #11

agent closed this issue