docs(vtex-io-app-settings): cover major-version scoping of saved settings - #89
Open
mateussaggin wants to merge 1 commit into
Open
docs(vtex-io-app-settings): cover major-version scoping of saved settings#89mateussaggin wants to merge 1 commit into
mateussaggin wants to merge 1 commit into
Conversation
…ings Saved app settings are addressed by the app's major version range, so they persist across minor and patch releases but start empty on a new major. This was missing from the skill, and it fails quietly: the app just reads schema defaults, so a flag that gated a behavior reverts and the feature silently turns off for every merchant with no error to detect. Verified against the Apps API, where only the major locator resolves: vtex.<app>@3.x returns the saved settings while @3.6.1 and @3.0.0 both return app_not_found. Adds decision rules, a hard constraint with paired examples, failure modes and checklist items covering fail-safe defaults, re-applying settings during a major upgrade, and keeping kill switches in version-independent storage.
🛡️ SDD Check — action requiredI couldn't detect an SDD in this PR. Please check one option below (requires write access to the repo):
|
Contributor
|
✅ Validation passed — all checks OK Full validation output |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The
vtex-io-app-settingsskill did not mention that saved app settings are scoped to the app's major version range. This gap matters because the failure is silent.Settings persist across minor and patch releases, but a new major starts from an empty settings object. Nothing errors — the app simply reads
settingsSchemadefaults — so a flag that gated a behavior reverts to its default and the feature turns off for every merchant with no signal that anything changed. Reading settings at runtime hides the distinction entirely, becausegetAppSettings(process.env.VTEX_APP_ID)resolvesvtex.my-app@3.6.1to the3.xscope automatically.This came out of a real investigation on a B2B app where feature flags gate session-transform behavior, and the question "what happens to merchant config when we release?" had no answer in the skill.
How the scoping was verified
Queried the Apps API for the same installed app with different locators. Only the major range resolves:
vtex.<app>@3.6.1app_not_foundvtex.<app>@3.0.0app_not_foundvtex.<app>@3.xvtex.<app>(no version)What changed
Edited the source at
tracks/vtex-io/skills/vtex-io-app-settings/skill.md, then regenerated artifacts withbun run exportand replicated the CI sync steps (rules/fromexports/cursor/,skills/fromexports/opencode/).settingsSchema.No existing guidance was changed or removed; the diff is additive (+742, no deletions).
Test plan
bun run validate—vtex-io-app-settingspasses 13/13 checksbun run exportcompletes; regenerated artifacts committedrules/*.mdcfromexports/cursor/,skills/fromexports/opencode/) sogit diff exports/ rules/ skills/is clean against the committed treefaststore-storefront, untouched here)