From 57cd8c8670b6b536216fc1f11e76a4766dbf79dd Mon Sep 17 00:00:00 2001 From: Gaven Lan Ren Date: Wed, 28 Oct 2026 10:55:43 -0400 Subject: [PATCH 1/2] docs(extensions): name the runtime local override file Use local-config.yml in the user guide, API reference, development guide, CLI reference, and template comments. ConfigManager and the managed ignore rule already use that name; the old instructions silently failed to apply. Validation: 21 existing ConfigManager checks and 4 managed-ignore checks passed. Reproduced the old filename being ignored by ConfigManager and verified the documented filename overrides project.key and is gitignored. git diff --check passed. No runtime behavior or configuration values change. Fixes github/spec-kit#5083 Assisted-by: OpenAI Codex (model: unknown, autonomous) --- docs/reference/extensions.md | 4 ++-- extensions/EXTENSION-API-REFERENCE.md | 4 ++-- extensions/EXTENSION-DEVELOPMENT-GUIDE.md | 2 +- extensions/EXTENSION-USER-GUIDE.md | 8 ++++---- extensions/template/config-template.yml | 2 +- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/reference/extensions.md b/docs/reference/extensions.md index 4c93f94dbe..24afd8c68f 100644 --- a/docs/reference/extensions.md +++ b/docs/reference/extensions.md @@ -276,7 +276,7 @@ Most extensions include configuration files in their install directory: ```text .specify/extensions// ├── -config.yml # Project config (version controlled) -├── -config.local.yml # Local overrides (gitignored) +├── local-config.yml # Local overrides (gitignored) └── -config.template.yml # Template reference ``` @@ -284,7 +284,7 @@ Configuration is merged in this order (highest priority last): 1. **Extension defaults** (from `extension.yml`) 2. **Project config** (`-config.yml`) -3. **Local overrides** (`-config.local.yml`) +3. **Local overrides** (`local-config.yml`) 4. **Environment variables** (`SPECKIT__*`) To set up configuration for a newly installed extension, copy the template: diff --git a/extensions/EXTENSION-API-REFERENCE.md b/extensions/EXTENSION-API-REFERENCE.md index 2be2f43123..4c2e032714 100644 --- a/extensions/EXTENSION-API-REFERENCE.md +++ b/extensions/EXTENSION-API-REFERENCE.md @@ -562,7 +562,7 @@ field_mappings: 1. **Extension Defaults** (from `extension.yml` `defaults` section) 2. **Project Config** (`{extension-id}-config.yml`) -3. **Local Override** (`{extension-id}-config.local.yml`, gitignored) +3. **Local Override** (`local-config.yml`, gitignored) 4. **Environment Variables** (`SPECKIT_{EXTENSION}_*`) ### Environment Variable Pattern @@ -884,7 +884,7 @@ satisfied = version_satisfies("1.2.3", ">=1.0.0,<2.0.0") # bool │ ├── {extension-id}/ # Extension directory │ │ ├── extension.yml # Manifest │ │ ├── {ext}-config.yml # User config -│ │ ├── {ext}-config.local.yml # Local overrides (gitignored) +│ │ ├── local-config.yml # Local overrides (gitignored) │ │ ├── {ext}-config.template.yml # Template │ │ ├── commands/ # Command files │ │ │ └── *.md diff --git a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md b/extensions/EXTENSION-DEVELOPMENT-GUIDE.md index a263a7bbf1..5292a670dc 100644 --- a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md +++ b/extensions/EXTENSION-DEVELOPMENT-GUIDE.md @@ -385,7 +385,7 @@ In your command, load config with layered precedence: 1. Extension defaults (`extension.yml` → `defaults`) 2. Project config (`.specify/extensions/my-ext/my-ext-config.yml`) -3. Local overrides (`.specify/extensions/my-ext/my-ext-config.local.yml` - gitignored) +3. Local overrides (`.specify/extensions/my-ext/local-config.yml` - gitignored) 4. Environment variables (`SPECKIT_MY_EXT_*`) **Example loading script**: diff --git a/extensions/EXTENSION-USER-GUIDE.md b/extensions/EXTENSION-USER-GUIDE.md index 04b5e1edc0..9c179dfe3e 100644 --- a/extensions/EXTENSION-USER-GUIDE.md +++ b/extensions/EXTENSION-USER-GUIDE.md @@ -348,7 +348,7 @@ Extensions can have multiple configuration files: ```text .specify/extensions/jira/ ├── jira-config.yml # Main config (version controlled) -├── jira-config.local.yml # Local overrides (gitignored) +├── local-config.yml # Local overrides (gitignored) └── jira-config.template.yml # Template (reference) ``` @@ -358,7 +358,7 @@ Configuration is merged in this order (highest priority last): 1. **Extension defaults** (from `extension.yml`) 2. **Project config** (`jira-config.yml`) -3. **Local overrides** (`jira-config.local.yml`) +3. **Local overrides** (`local-config.yml`) 4. **Environment variables** (`SPECKIT_JIRA_*`) ### Example: Jira Configuration @@ -374,7 +374,7 @@ defaults: labels: ["spec-driven"] ``` -**Local override** (`.specify/extensions/jira/jira-config.local.yml`): +**Local override** (`.specify/extensions/jira/local-config.yml`): ```yaml project: @@ -907,7 +907,7 @@ To install: `specify extension add jira` Use local config for development: ```yaml -# .specify/extensions/jira/jira-config.local.yml +# .specify/extensions/jira/local-config.yml project: key: "DEVTEST" # Your test project diff --git a/extensions/template/config-template.yml b/extensions/template/config-template.yml index 74725373d7..d6e4abe7e6 100644 --- a/extensions/template/config-template.yml +++ b/extensions/template/config-template.yml @@ -71,5 +71,5 @@ advanced: # Note: Use uppercase and replace dots with underscores # Local Overrides: -# For local development, create my-extension-config.local.yml (gitignored) +# For local development, create local-config.yml (gitignored) # to override settings without affecting the team configuration From da2483baccb1f9925be1db3433ab88269137225f Mon Sep 17 00:00:00 2001 From: Gaven Lan Ren Date: Wed, 28 Oct 2026 11:51:03 -0400 Subject: [PATCH 2/2] docs(extensions): ignore the documented local override file Address PR #5159 review by correcting both user-guide ignore examples and adding local-config.yml to the extension source template's ignore rules. Preserve the legacy template pattern for compatibility. Validation: temporary Git repositories reproduce both missed local-config.yml matches before the change. Afterward, the template ignores current and legacy override names, the guide snippet ignores installed local-config.yml, and ordinary project configs remain trackable (five real Git checks passed). git diff --check passed. Assisted-by: OpenAI Codex (model: unknown, autonomous) --- extensions/EXTENSION-USER-GUIDE.md | 4 ++-- extensions/template/.gitignore | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/extensions/EXTENSION-USER-GUIDE.md b/extensions/EXTENSION-USER-GUIDE.md index 9c179dfe3e..b2459700d1 100644 --- a/extensions/EXTENSION-USER-GUIDE.md +++ b/extensions/EXTENSION-USER-GUIDE.md @@ -868,7 +868,7 @@ specify extension add --dev /path/to/extension - `.specify/extensions/.cache/` (catalog cache) - `.specify/extensions/.backup/` (config backups) -- `.specify/extensions/*/*.local.yml` (local overrides) +- `.specify/extensions/*/local-config.yml` (local overrides) - `.specify/extensions/.registry` (installation state) Add to `.gitignore`: @@ -876,7 +876,7 @@ Add to `.gitignore`: ```gitignore .specify/extensions/.cache/ .specify/extensions/.backup/ -.specify/extensions/*/*.local.yml +.specify/extensions/*/local-config.yml .specify/extensions/.registry ``` diff --git a/extensions/template/.gitignore b/extensions/template/.gitignore index 1f7b132a76..9ca5bcb500 100644 --- a/extensions/template/.gitignore +++ b/extensions/template/.gitignore @@ -1,4 +1,5 @@ # Local configuration overrides +local-config.yml *-config.local.yml # Python