Skip to content
Documentation

ADR-0004 Astro Version Divergence

Status

Section titled “Status”

Accepted

Context

Section titled “Context”

The marketing site (apps/site) benefits from Astro 6 beta features, while the documentation site (apps/docs) relies on Starlight 0.37.4, which presently supports Astro 5. Upgrading docs to Astro 6 would break Starlight integration.

Decision

Section titled “Decision”
  • Maintain Astro 6 beta for apps/site.
  • Keep apps/docs on Astro 5.16.15 with Starlight 0.37.4 until official support for Astro 6 is available.
  • Review compatibility quarterly and document outcomes.

Rationale

Section titled “Rationale”
  • Enables marketing to iterate with modern features.
  • Preserves stability for documentation and avoids unsupported Starlight paths.
  • Balances innovation and reliability between public and internal surfaces.

Consequences

Section titled “Consequences”
  • Mixed dependency graph; maintain diligence when updating shared tooling.
  • Additional testing required when upgrading pnpm or shared packages.
  • Documentation of divergence needed for onboarding and audits.

Deferred Considerations

Section titled “Deferred Considerations”
  • Aligning versions once Starlight supports Astro 6.
  • Evaluating whether a shared component library requires a common Astro baseline.
  • Considering automated tests to detect incompatible dependency updates.

Implementation Steps

Section titled “Implementation Steps”
  1. Track version updates in Version Policy.
  2. Run pnpm build:site and pnpm build:docs to confirm compatibility after any upgrade.
  3. Update this ADR when the version stance changes.

Verification Method

Section titled “Verification Method”
  • Successful local builds inside Docker for both apps.
  • Starlight sidebar and integrations remain functional after upgrades.
  • Quarterly review documented in version policy notes.