eric/ConfigKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Settle discovery presets and directory helpers

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-24 01:33:53 +00:00
parent 367bbaaa1b
commit ae038a5165
1 changed files with 32 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
docs/roadmap/discovery.md
View File

@@ -1,7 +1,7 @@
# Composable Configuration Discovery Roadmap
Status: proposal with the agreed direction, filename groups, and Unix system
preset captured below. Remaining preset and behavioral choices are under
Status: proposal with the agreed direction, filename groups, and search presets
captured below. Remaining behavioral choices are under
[Open Decisions](#open-decisions).
This document describes future work, not an implemented contract. A staged
implementation plan will follow once the decisions are settled.
@@ -113,6 +113,35 @@ This produces 14 candidates: six in each application-specific directory, then
`/etc/<appname>/<appname>.yml`. Selecting only `Named` for `/etc` is an ordinary
directory-search description; the selection algorithm needs no special exception.
### Additional Presets (OD-1 — Settled)
Provide the following independently selectable presets alongside Unix system.
Within each preset, search directories in the order shown:
| Preset | Directory | Filename groups, in order |
| --- | --- | --- |
| User configuration | `<user-config-dir>/<appname>` | `[Named, Generic]` |
| User configuration | `<user-config-dir>` | `[Named]` |
| Home directory | `<home>/.<appname>` | `[Named, Generic]` |
| Home directory | `<home>` | `[Named]` |
| Working directory | Current working directory | `[Named]` |
Resolve the user-configuration base with
[`os.UserConfigDir`](https://pkg.go.dev/os#UserConfigDir), the home base with
[`os.UserHomeDir`](https://pkg.go.dev/os#UserHomeDir), and the working-directory
base with [`os.Getwd`](https://pkg.go.dev/os#Getwd). Adopt the Go helpers'
platform-specific directory and environment behavior, including their errors;
OD-2 determines how discovery responds to a resolution error.
The goal is to support familiar conventions through idiomatic Go. This feature
does not add a separate XDG compatibility layer or XDG system preset. A selected
user-configuration base has no additional hard-coded `<home>/.config` fallback.
The Home directory preset is a separate, explicit choice.
The working-directory preset searches only that directory and uses application-named
files; it does not walk ancestor directories. The consumer chooses precedence
between all presets. Selecting one does not automatically select any others.
### Illustrative Consumer API
Names below are illustrative and are not implemented Go API:
@@ -239,31 +268,6 @@ its in-progress changes are part of a fixed implementation baseline.
## Open Decisions
### OD-1 — Additional Preset Locations
The filename groups, default `[Named, Generic]` order, and Unix system preset
are settled above. The remaining choice is which additional directory conventions
to provide as presets.
**Recommendation:** also provide user-configuration and working-directory presets:
| Preset | Directory | Filename groups, in order |
| --- | --- | --- |
| User configuration | `<user-config-dir>/<appname>` | `[Named, Generic]` |
| Working directory | Current working directory | `[Named, Generic]` |
For the user preset, use Go's platform-specific
[`os.UserConfigDir`](https://pkg.go.dev/os#UserConfigDir) as the base. This supplies
a conventional user location without inventing separate home-directory rules.
The working-directory preset searches that directory without walking ancestors.
Both reuse the agreed default filename groups.
**Alternative:** provide a home-directory convention, such as
`~/.<appname>/` with `[Named, Generic]`, instead of or alongside the
user-config-directory preset. It is familiar for some tools, but providing both
adds another convention for consumers to select and order. Prefer the
user-config-directory preset initially; custom searches can express other layouts.
### OD-2 — Unavailable Bases And Platform Applicability
**Recommendation:** resolve directory bases as the ordered search reaches them.
@@ -271,7 +275,7 @@ If a selected directory's base cannot be resolved, report an error. Treat using
Unix system preset on a platform where it is unsupported as an explicit
configuration error when that preset is reached. Specify the supported platforms
in the implementation plan. Do not silently translate the Unix preset into a
different platform's convention. User and working-directory presets use their
different platform's convention. User, home, and working-directory presets use their
platform-native bases.
An unavailable base is different from a candidate file being absent. Failure to