Versioning coordination pattern for multi-component Foundry apps

[mraible]

Foundry apps with both UI (pages/extensions) and backend functions have no built-in mechanism to keep version strings in sync across components. This leads to silent deployment confusion where the browser-cached UI doesn't match the deployed function backend.

This issue proposes a lightweight versioning coordination pattern for the skills to recommend (and optionally scaffold).

Problem

A typical Foundry app has version strings in multiple places:

Layer	Location	Example
Python function	functions/<name>/version.py	__version__ = "1.2.3"
Go function	functions/<name>/version.go	const Version = "1.2.3"
UI page	ui/pages/<name>/package.json	"version": "1.2.3"
UI extension	ui/extensions/<name>/package.json	"version": "1.2.3"

Nothing enforces these stay in sync. The platform's deploy/release cycle doesn't validate internal version consistency, and browser caching can make a stale UI appear to work against a newer backend.

Proposed Pattern

1. Version display component (high value, low effort)

A recommended pattern in ui-development for apps with function backends: a "Settings" or "About" tab that fetches and displays both frontend and backend versions at runtime.

// UI side
const response = await falcon.connect().postCommand('get-version');
// Shows: UI 1.2.3 | Backend 1.2.3

# Function side - version endpoint
from version import __version__
def handle_get_version(request):
    return {"backend": __version__}

This serves as a runtime assertion that deploy completed correctly and the browser isn't caching stale assets.

2. Coordinated version bump script (medium value, opt-in)

A generic scripts/bump_version.py that auto-discovers components from manifest.yml and bumps all version strings together:

python3 scripts/bump_version.py patch   # 1.2.3 → 1.2.4 everywhere
python3 scripts/bump_version.py minor   # 1.2.3 → 1.3.0 everywhere
python3 scripts/bump_version.py major   # 1.2.3 → 2.0.0 everywhere

Auto-discovery logic:

• Parse manifest.yml for function paths → look for version.py or version.go
• Walk ui/pages/*/package.json and ui/extensions/*/package.json
• Bump all to the same semver value

3. Workflow checkpoint in development-workflow (documentation)

Document the recommended lifecycle position for version bumps:

write code → test → fix → test passes → BUMP VERSION → git commit → git push
                                              ↑
                                     quality gate lives here
                                              ↓
                          foundry apps validate → deploy → release

Key principles to document:

• Bump before commit, not before deploy - versions are a git concern, deploy/release is just delivery
• Roll forward, never back - if a rollback is needed, branch from a previous working version, bump forward, deploy the new version
• Monotonically increasing - every commit has an accurate version, every deploy matches source control

Open Questions

1. Is this useful broadly, or just for power users building complex apps? Simple single-function apps may not need this overhead.
2. Should the skills scaffold the bump script during app creation? Or just document the pattern and link to a template?
3. Makefile vs npm scripts vs standalone script? The principle (single command bumps all artifacts) matters more than the tool. The proposal uses a standalone Python script since all Foundry apps already require Python or Go.
4. Should the development-workflow skill enforce a version check pre-deploy? (e.g., warn if version.py hasn't changed since last deploy) Or is that too opinionated?

Credit

This pattern emerged from conversation with @scott-macgregor who built versioning tooling for his Vue3 + Python Foundry apps and shared the approach.

[mraible]

Additional context from discussion:

Platform version numbers are opaque sequential integers. The Foundry CLI does not let you set an explicit version on deploy or release. It assigns deployment/release numbers sequentially (deploy 1, 2, 3... release 1, 2, 3...). You cannot say "this is release 1.4.0." So there is an inherent mismatch between internal semver (npm/python) and platform-assigned counters.

This means the coordinated bump script is purely a developer-side concern for tracking "what code is in this commit." The platform release number becomes a counter you mostly ignore in favor of your own version scheme. The version display pattern (settings tab) bridges this gap by showing your real version at runtime.

Foundry likely ignores package.json version entirely. The platform consumes the dist/ output from UI builds, not the source package.json. So the version in package.json is for developer bookkeeping and git history, not something the platform reads or enforces. This reinforces that versioning is a developer workflow concern, not a platform concern. The value is:

1. Knowing what code a given git commit represents
2. Being able to display it at runtime via the version endpoint
3. Detecting drift (did my deploy actually land?)

The platform will never validate or use your package.json version, which is why it is easy for versions to drift silently in the first place.

[cs-shadowbq]

Mock out the other kinds of foundry apps too, Since some projects have no package.json (it's plain JS, no npm/node build), use a version.json at the root as the single source of truth, and have the config.js files reference it at build/deploy time via the bump script.