From ae038a5165dda8cab1f502acdd1a07e54a386783 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 24 Oct 2026 01:33:53 +0000 Subject: [PATCH] Settle discovery presets and directory helpers --- docs/roadmap/discovery.md | 60 +++++++++++++++++++++------------------ 1 file changed, 32 insertions(+), 28 deletions(-) diff --git a/docs/roadmap/discovery.md b/docs/roadmap/discovery.md index 95fa51d..ad8028d 100644 --- a/docs/roadmap/discovery.md +++ b/docs/roadmap/discovery.md @@ -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//.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 | `/` | `[Named, Generic]` | +| User configuration | `` | `[Named]` | +| Home directory | `/.` | `[Named, Generic]` | +| Home directory | `` | `[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 `/.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 | `/` | `[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 -`~/./` 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