diff --git a/AGENTS.md b/AGENTS.md index 43a078ce..8f7e1adb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -209,7 +209,7 @@ Native and E2E examples; narrow with test-file, suite, scheme, or flow arguments - Follow [`STYLE_GUIDE.md`](./STYLE_GUIDE.md) for human-authored prose. Authored docs live in `documentation/`; generated TypeDoc output lives in `docs/`. - Preserve existing README families: repo/package/reference implementation headers, navigation, and - pre-release warnings; documentation indexes; short status READMEs for placeholders or + release-status warnings where applicable; documentation indexes; short status READMEs for placeholders or internal-only surfaces. - Use sentence-case Markdown headings, official product/API casing, fenced code blocks with language tags, and `pnpm` commands. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f23a15e6..ea011553 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,10 +16,6 @@ -> [!WARNING] -> -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. - We appreciate community contributions in the form of issues and pull requests. Use this guide when you change SDK packages, reference implementations, documentation, release @@ -104,8 +100,8 @@ pnpm version:pnpm | -------------------- | ----------------------------------------------------------------------------------- | | `lib/` | Internal shared tooling and mock services, such as `build-tools` and `mocks` | | `packages/` | Workspace packages, including published SDKs and framework layers | -| `packages/android/` | Pre-release Android library | -| `packages/ios/` | Pre-release Swift package | +| `packages/android/` | Beta Android library | +| `packages/ios/` | Beta Swift package | | `implementations/` | Reference apps used for integration testing, validation evidence, and E2E coverage | | `documentation/` | Authored guides and concepts published with TypeDoc | | `docs/` | Generated TypeDoc output | diff --git a/README.md b/README.md index bb41f5b6..4a09553b 100644 --- a/README.md +++ b/README.md @@ -16,10 +16,6 @@ -> [!WARNING] -> -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. - ## Introduction A [pnpm](https://pnpm.io/) monorepo hosting a suite of SDKs, supporting libraries, and reference @@ -91,21 +87,21 @@ General selection rules: ## Native and planned SDKs -React Native support is available through +React Native support is available as a beta SDK through [`@contentful/optimization-react-native`](./packages/react-native-sdk/README.md). -Native iOS work is also present in this repository as a pre-release Swift Package under +Native iOS work is also present in this repository as a beta Swift Package under [`packages/ios`](./packages/ios/README.md), backed by the shared [`@contentful/optimization-js-bridge`](./packages/universal/optimization-js-bridge/README.md) adapter and the [iOS reference app](./implementations/ios-sdk/README.md). Treat this surface as -alpha implementation work rather than a stable public native SDK. +beta implementation work rather than a stable public native SDK. -Native Android support is also present as a pre-release Kotlin Android library under +Native Android support is also present as a beta Kotlin Android library under [`packages/android`](./packages/android/README.md), published as the Maven AAR `com.contentful.java:optimization-android`, backed by the shared [`@contentful/optimization-js-bridge`](./packages/universal/optimization-js-bridge/README.md) adapter and the [Android reference app](./implementations/android-sdk/README.md). Treat this surface -as alpha implementation work rather than a stable public native SDK. +as beta implementation work rather than a stable public native SDK. The following framework SDKs are planned but are not published from this repository: diff --git a/documentation/authoring/recipes/integration.md b/documentation/authoring/recipes/integration.md index 46f9f0ff..799091f0 100644 --- a/documentation/authoring/recipes/integration.md +++ b/documentation/authoring/recipes/integration.md @@ -32,7 +32,6 @@ is explicit in the blueprint; shared copy must not infer an SDK family or restat Voice: plain and direct, warm but not chatty. No hype or filler that reads oddly in a reference doc ("this is the payoff", "the magic happens here", "boom", gratuitous "just"). Describe the current SDK in present tense — never narrate change ("no longer", "now supports", "used to", PR/issue numbers). -While the SDK is pre-release, document the single current version; do not compare SDK versions. Structure invariants (`pnpm guides:check` enforces the blueprint-to-guide section and category map): diff --git a/documentation/guides/README.md b/documentation/guides/README.md index 34499e14..d1c90daa 100644 --- a/documentation/guides/README.md +++ b/documentation/guides/README.md @@ -42,7 +42,7 @@ Server and web SDK guides are listed before native and mobile SDK guides. ### Native and mobile SDKs -Native iOS and Android guides route to pre-release alpha surfaces. +Native and mobile SDK guides route to beta SDK surfaces. | Guide | Runtime or app type | Package | | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- | ------------------------------------------ | diff --git a/documentation/guides/choosing-the-right-sdk.md b/documentation/guides/choosing-the-right-sdk.md index d6ad5cd7..10f84cdd 100644 --- a/documentation/guides/choosing-the-right-sdk.md +++ b/documentation/guides/choosing-the-right-sdk.md @@ -53,30 +53,30 @@ runtime-specific tracking, consent UI, or framework integration. For mobile apps, choose `@contentful/optimization-react-native` when the mobile app is built with JavaScript or TypeScript in React Native. Choose the native iOS or Android SDK only for -platform-native apps that can accept alpha native API and setup changes. +platform-native apps that can accept beta native API and setup changes. > [!WARNING] > -> Public package READMEs mark the Optimization SDK Suite as pre-release alpha. Plan for breaking -> changes while adopting these packages. +> The React Native, iOS, and Android SDKs are in beta. Plan for breaking changes while adopting native +> SDKs. ## Decision table Use this table to choose the primary package and the next integration guide: -| Reader need | Choose | Why | Next guide | -| ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| Nest.js app, Node server, server function, or SSR layer outside the Next.js adapter | `@contentful/optimization-node` | It provides stateless, request-scoped profile evaluation, event emission, managed Contentful entry fetching and prefetching, entry resolution, and caching guidance for Node runtimes. | [Integrating the Optimization Node SDK in a Node app](./integrating-the-node-sdk-in-a-node-app.md) | -| Angular, Vue, Svelte, Web Components, non-React browser app, or custom browser framework app | `@contentful/optimization-web` | It owns browser consent state, anonymous ID persistence, managed Contentful entry fetching and prefetching, automatic entry interaction tracking, browser event delivery, and Web Components. | [Integrating the Optimization Web SDK in a web app](./integrating-the-web-sdk-in-a-web-app.md) | -| React browser app outside Next.js integration | `@contentful/optimization-react-web` | It wraps the Web SDK with React providers, hooks, router page tracking, optimized entry rendering by entry ID, interaction tracking, and live update semantics. | [Integrating the Optimization React Web SDK in a React app](./integrating-the-react-web-sdk-in-a-react-app.md) | -| Next.js App Router app with server-personalized first paint and browser re-resolution after hydration | `@contentful/optimization-nextjs/app-router` | Its `/app-router` bound `OptimizationRoot`, `OptimizedEntry`, and route tracker keep personalized initial HTML before the browser SDK owns reactive entry resolution, live updates, route events, and preview-panel attachment. | [Integrating the Optimization Next.js SDK in a Next.js App Router app](./integrating-the-optimization-sdk-in-a-nextjs-app-router-app.md) | -| Next.js Pages Router app with `getServerSideProps` personalization | `@contentful/optimization-nextjs/pages-router` plus `/pages-router/server` | Its `/pages-router` components and `/pages-router/server` helper pass server Optimization state through `pageProps` and avoid duplicate initial page events. | [Integrating the Optimization Next.js SDK in a Next.js Pages Router app](./integrating-the-optimization-sdk-in-a-nextjs-pages-router-app.md) | -| Custom JavaScript runtime or framework adapter where no official SDK fits | `@contentful/optimization-core` plus `@contentful/optimization-core/entry-source` | Core provides shared state and resolution primitives. The entry-source subpath manages baseline-entry or entry-ID source lifecycle while the adapter owns rendering, tracking, and runtime policy. | [Building a custom JavaScript Optimization adapter](./building-a-custom-javascript-optimization-adapter.md) | -| React Native app | `@contentful/optimization-react-native` | It provides a stateful JavaScript mobile runtime with React providers, hooks, `OptimizedEntry`, screen tracking, optional offline-aware delivery, and preview-panel support. | [Integrating the Optimization React Native SDK in a React Native app](./integrating-the-react-native-sdk-in-a-react-native-app.md) | -| Native iOS app built with SwiftUI that accepts alpha native API and setup changes | `ContentfulOptimization` Swift Package | It provides native Swift APIs, SwiftUI helpers, persistence, networking, lifecycle handling, screen tracking, entry rendering, and preview-panel UI. | [Integrating the Optimization iOS SDK in a SwiftUI app](./integrating-the-optimization-ios-sdk-in-a-swiftui-app.md) | -| Native iOS app built with UIKit or direct client ownership that accepts alpha native API and setup changes | `ContentfulOptimization` Swift Package | It exposes the same native iOS runtime through direct client APIs and UIKit-compatible preview, screen tracking, and entry-rendering patterns. | [Integrating the Optimization iOS SDK in a UIKit app](./integrating-the-optimization-ios-sdk-in-a-uikit-app.md) | -| Native Android app built with Jetpack Compose that accepts alpha native API and setup changes | `com.contentful.java:optimization-android` | The Android AAR includes the stateful Kotlin client, Compose UI helpers, screen tracking, entry optimization, preview controls, and offline event delivery. | [Integrating the Optimization Android SDK in a Jetpack Compose app](./integrating-the-optimization-android-sdk-in-a-compose-app.md) | -| Native Android app built with Android Views or XML layouts that accepts alpha native API and setup changes | `com.contentful.java:optimization-android` | The same Android AAR includes Android Views helpers such as `OptimizationManager`, `OptimizedEntryView`, `ScreenTracker`, preview controls, and the stateful client. | [Integrating the Optimization Android SDK in an Android Views app](./integrating-the-optimization-android-sdk-in-a-views-app.md) | +| Reader need | Choose | Why | Next guide | +| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| Nest.js app, Node server, server function, or SSR layer outside the Next.js adapter | `@contentful/optimization-node` | It provides stateless, request-scoped profile evaluation, event emission, managed Contentful entry fetching and prefetching, entry resolution, and caching guidance for Node runtimes. | [Integrating the Optimization Node SDK in a Node app](./integrating-the-node-sdk-in-a-node-app.md) | +| Angular, Vue, Svelte, Web Components, non-React browser app, or custom browser framework app | `@contentful/optimization-web` | It owns browser consent state, anonymous ID persistence, managed Contentful entry fetching and prefetching, automatic entry interaction tracking, browser event delivery, and Web Components. | [Integrating the Optimization Web SDK in a web app](./integrating-the-web-sdk-in-a-web-app.md) | +| React browser app outside Next.js integration | `@contentful/optimization-react-web` | It wraps the Web SDK with React providers, hooks, router page tracking, optimized entry rendering by entry ID, interaction tracking, and live update semantics. | [Integrating the Optimization React Web SDK in a React app](./integrating-the-react-web-sdk-in-a-react-app.md) | +| Next.js App Router app with server-personalized first paint and browser re-resolution after hydration | `@contentful/optimization-nextjs/app-router` | Its `/app-router` bound `OptimizationRoot`, `OptimizedEntry`, and route tracker keep personalized initial HTML before the browser SDK owns reactive entry resolution, live updates, route events, and preview-panel attachment. | [Integrating the Optimization Next.js SDK in a Next.js App Router app](./integrating-the-optimization-sdk-in-a-nextjs-app-router-app.md) | +| Next.js Pages Router app with `getServerSideProps` personalization | `@contentful/optimization-nextjs/pages-router` plus `/pages-router/server` | Its `/pages-router` components and `/pages-router/server` helper pass server Optimization state through `pageProps` and avoid duplicate initial page events. | [Integrating the Optimization Next.js SDK in a Next.js Pages Router app](./integrating-the-optimization-sdk-in-a-nextjs-pages-router-app.md) | +| Custom JavaScript runtime or framework adapter where no official SDK fits | `@contentful/optimization-core` plus `@contentful/optimization-core/entry-source` | Core provides shared state and resolution primitives. The entry-source subpath manages baseline-entry or entry-ID source lifecycle while the adapter owns rendering, tracking, and runtime policy. | [Building a custom JavaScript Optimization adapter](./building-a-custom-javascript-optimization-adapter.md) | +| React Native app | `@contentful/optimization-react-native` | It provides a stateful JavaScript mobile runtime with React providers, hooks, `OptimizedEntry`, screen tracking, optional offline-aware delivery, and preview-panel support. | [Integrating the Optimization React Native SDK in a React Native app](./integrating-the-react-native-sdk-in-a-react-native-app.md) | +| Native iOS app built with SwiftUI that accepts beta native API and setup changes | `ContentfulOptimization` Swift Package | It provides native Swift APIs, SwiftUI helpers, persistence, networking, lifecycle handling, screen tracking, entry rendering, and preview-panel UI. | [Integrating the Optimization iOS SDK in a SwiftUI app](./integrating-the-optimization-ios-sdk-in-a-swiftui-app.md) | +| Native iOS app built with UIKit or direct client ownership that accepts beta native API and setup changes | `ContentfulOptimization` Swift Package | It exposes the same native iOS runtime through direct client APIs and UIKit-compatible preview, screen tracking, and entry-rendering patterns. | [Integrating the Optimization iOS SDK in a UIKit app](./integrating-the-optimization-ios-sdk-in-a-uikit-app.md) | +| Native Android app built with Jetpack Compose that accepts beta native API and setup changes | `com.contentful.java:optimization-android` | The Android AAR includes the stateful Kotlin client, Compose UI helpers, screen tracking, entry optimization, preview controls, and offline event delivery. | [Integrating the Optimization Android SDK in a Jetpack Compose app](./integrating-the-optimization-android-sdk-in-a-compose-app.md) | +| Native Android app built with Android Views or XML layouts that accepts beta native API and setup changes | `com.contentful.java:optimization-android` | The same Android AAR includes Android Views helpers such as `OptimizationManager`, `OptimizedEntryView`, `ScreenTracker`, preview controls, and the stateful client. | [Integrating the Optimization Android SDK in an Android Views app](./integrating-the-optimization-android-sdk-in-a-views-app.md) | ## Alternatives diff --git a/implementations/AGENTS.md b/implementations/AGENTS.md index a41af3eb..26a92c1a 100644 --- a/implementations/AGENTS.md +++ b/implementations/AGENTS.md @@ -27,9 +27,9 @@ Applies to reference implementations and shared implementation contracts under ` - Follow root Markdown rules and [`../STYLE_GUIDE.md`](../STYLE_GUIDE.md). - Use the repo-standard header, implementation-specific `

`, Readme/Guides/Reference/Contributing - navigation, pre-release warning, and an introduction naming the SDK packages they integrate and - the customer-style integration path they validate. -- Use this default top-level order: header/navigation/warning, introduction naming the integrated + navigation, native beta status warning when applicable, and an introduction naming the SDK + packages they integrate and the customer-style integration path they validate. +- Use this default top-level order: header/navigation/status warning when applicable, introduction naming the integrated SDK package or native status, `## What this covers`, optional near-top architecture notes, `## CDA locale handling`, `## Prerequisites`, `## Setup`, `## Running locally`, `## Running E2E tests`, implementation-specific maintainer notes, and `## Related`. diff --git a/implementations/android-sdk/README.md b/implementations/android-sdk/README.md index 3e4c0e21..a32f981c 100644 --- a/implementations/android-sdk/README.md +++ b/implementations/android-sdk/README.md @@ -18,7 +18,7 @@ > [!WARNING] > -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. +> The Optimization Android SDK is in beta. Breaking changes can be published at any time. This is the native Android reference implementation for the [Contentful Optimization Android SDK](../../packages/android/README.md). It demonstrates the diff --git a/implementations/ios-sdk/README.md b/implementations/ios-sdk/README.md index ed473663..39b50748 100644 --- a/implementations/ios-sdk/README.md +++ b/implementations/ios-sdk/README.md @@ -18,14 +18,14 @@ > [!WARNING] > -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. +> The Optimization iOS SDK is in beta. Breaking changes can be published at any time. Reference app for native iOS bridge and preview-panel validation work. This app exercises two iOS shells against the mock server in `lib/mocks/` and hosts the XCUITest suite. > [!NOTE] > -> This reference app is not the iOS SDK package. The iOS SDK exists as a pre-release Swift Package; +> This reference app is not the iOS SDK package. The iOS SDK exists as a beta Swift Package; > for package status, see [`packages/ios`](../../packages/ios/README.md). ## What this demonstrates @@ -228,7 +228,7 @@ Common local pitfalls: ## Related -- [Optimization iOS SDK package](../../packages/ios/README.md) - Pre-release Swift Package status +- [Optimization iOS SDK package](../../packages/ios/README.md) - Beta Swift Package status and release notes - [Optimization iOS SDK code map](../../packages/ios/CODE_MAP.md) - Maintainer architecture map for the native iOS package diff --git a/implementations/nextjs-sdk_app-router/README.md b/implementations/nextjs-sdk_app-router/README.md index fb645a61..e7c6bbdb 100644 --- a/implementations/nextjs-sdk_app-router/README.md +++ b/implementations/nextjs-sdk_app-router/README.md @@ -16,10 +16,6 @@ -> [!WARNING] -> -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. - Reference implementation demonstrating `@contentful/optimization-nextjs` in a Next.js App Router application with bound server/client components, server-provided Optimization state handoff, and browser-side entry resolution after startup. The implementation binds `OptimizationRoot`, diff --git a/implementations/nextjs-sdk_pages-router/README.md b/implementations/nextjs-sdk_pages-router/README.md index 8889c57c..18a24d5a 100644 --- a/implementations/nextjs-sdk_pages-router/README.md +++ b/implementations/nextjs-sdk_pages-router/README.md @@ -16,10 +16,6 @@ -> [!WARNING] -> -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. - Reference implementation demonstrating `@contentful/optimization-nextjs` in a Next.js Pages Router application. Pages call `getServerSideOptimizationProps()` from `getServerSideProps`, pass the returned Optimization state through `pageProps`, and mount the bound Pages Router root and route diff --git a/implementations/node-sdk+web-sdk/README.md b/implementations/node-sdk+web-sdk/README.md index 70a3672a..2e2b07d6 100644 --- a/implementations/node-sdk+web-sdk/README.md +++ b/implementations/node-sdk+web-sdk/README.md @@ -16,10 +16,6 @@ -> [!WARNING] -> -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. - This is a reference implementation using both the [Optimization Node SDK](../../packages/node/node-sdk/README.md) and [Optimization Web SDK](../../packages/web/web-sdk/README.md), and is part of the diff --git a/implementations/node-sdk/README.md b/implementations/node-sdk/README.md index 7e074ebb..ab6ec832 100644 --- a/implementations/node-sdk/README.md +++ b/implementations/node-sdk/README.md @@ -16,10 +16,6 @@ -> [!WARNING] -> -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. - This is a reference implementation for the [Optimization Node SDK](../../packages/node/node-sdk/README.md) and is part of the [Contentful Optimization SDK Suite](../../README.md). diff --git a/implementations/react-native-sdk/README.md b/implementations/react-native-sdk/README.md index 53634301..dfa4877b 100644 --- a/implementations/react-native-sdk/README.md +++ b/implementations/react-native-sdk/README.md @@ -18,7 +18,7 @@ > [!WARNING] > -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. +> The Optimization React Native SDK is in beta. Breaking changes can be published at any time. This is a reference implementation for the [Optimization React Native SDK](../../packages/react-native-sdk/README.md) and is part of the diff --git a/implementations/react-web-sdk/README.md b/implementations/react-web-sdk/README.md index 1e5ed5e1..e0f8120f 100644 --- a/implementations/react-web-sdk/README.md +++ b/implementations/react-web-sdk/README.md @@ -16,10 +16,6 @@ -> [!WARNING] -> -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. - Reference implementation demonstrating `@contentful/optimization-react-web` usage in a React SPA. This is the primary React Web reference implementation for customer-style usage of the official React framework package. diff --git a/implementations/web-sdk/README.md b/implementations/web-sdk/README.md index 1f006a5c..2312eee8 100644 --- a/implementations/web-sdk/README.md +++ b/implementations/web-sdk/README.md @@ -16,10 +16,6 @@ -> [!WARNING] -> -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. - This is a reference implementation for the [Optimization Web SDK](../../packages/web/web-sdk/README.md) and is part of the [Contentful Optimization SDK Suite](../../README.md). diff --git a/implementations/web-sdk_angular/README.md b/implementations/web-sdk_angular/README.md index 28ae6652..0c1a0ec5 100644 --- a/implementations/web-sdk_angular/README.md +++ b/implementations/web-sdk_angular/README.md @@ -16,10 +16,6 @@ -> [!WARNING] -> -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. - Reference implementation demonstrating `@contentful/optimization-web` usage in an Angular application. It uses Angular services and standalone components directly with the Web SDK, without an Angular-specific SDK adapter. diff --git a/implementations/web-sdk_react/README.md b/implementations/web-sdk_react/README.md index d9d35453..da0e3723 100644 --- a/implementations/web-sdk_react/README.md +++ b/implementations/web-sdk_react/README.md @@ -16,10 +16,6 @@ -> [!WARNING] -> -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. - Reference implementation demonstrating `@contentful/optimization-web` usage in a React web application with a local adapter layer. diff --git a/packages/AGENTS.md b/packages/AGENTS.md index f7f0a59e..4daf21e5 100644 --- a/packages/AGENTS.md +++ b/packages/AGENTS.md @@ -16,7 +16,7 @@ Applies to all workspace packages under `packages/`. - Follow root Markdown rules and [`../STYLE_GUIDE.md`](../STYLE_GUIDE.md). - Public package READMEs use the repo-standard Contentful header, package-specific `

`, Guides, - Reference, Contributing links, pre-release warning, and SDK-layer summary. + Reference, Contributing links, native beta status warning when applicable, and SDK-layer summary. - Application-facing READMEs stay orientation-first: install, minimal initialization, common setup, critical caveats, and links to guides, reference implementations, and generated reference docs. - Lower-level package READMEs are maintainer-oriented: direct users, stack position, minimal diff --git a/packages/android/README.md b/packages/android/README.md index 7ccbb8f3..48fce34e 100644 --- a/packages/android/README.md +++ b/packages/android/README.md @@ -17,9 +17,9 @@ > [!WARNING] > -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. +> The Optimization Android SDK is in beta. Breaking changes can be published at any time. -The Optimization Android SDK is a pre-release Kotlin Android library for native Android +The Optimization Android SDK is a beta Kotlin Android library for native Android applications. It is part of the [Contentful Optimization SDK Suite](../../README.md) and runs shared optimization behavior through a local QuickJS bridge while Kotlin code owns native app concerns such as persistence, networking, lifecycle handling, Jetpack Compose UI, XML Views UI, and preview-panel diff --git a/packages/ios/CODE_MAP.md b/packages/ios/CODE_MAP.md index 0d32f527..1b906fda 100644 --- a/packages/ios/CODE_MAP.md +++ b/packages/ios/CODE_MAP.md @@ -2,7 +2,7 @@ ## High-level overview -This directory contains the pre-release **Contentful Optimization iOS SDK** — a Swift Package (iOS +This directory contains the beta **Contentful Optimization iOS SDK** — a Swift Package (iOS 15+/macOS 12+) that enables content optimization and analytics tracking for native iOS apps. The SDK runs the existing JavaScript optimization core inside a **JavaScriptCore** context, bridged by a TypeScript adapter layer. Swift code handles native concerns (persistence, networking, app diff --git a/packages/ios/ContentfulOptimization/README.md b/packages/ios/ContentfulOptimization/README.md index 22a9f556..fd9c227b 100644 --- a/packages/ios/ContentfulOptimization/README.md +++ b/packages/ios/ContentfulOptimization/README.md @@ -18,7 +18,7 @@ > [!WARNING] > -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. +> The Optimization iOS SDK is in beta. Breaking changes can be published at any time. > [!NOTE] > diff --git a/packages/ios/README.md b/packages/ios/README.md index eaaa4c9d..41e6d045 100644 --- a/packages/ios/README.md +++ b/packages/ios/README.md @@ -17,9 +17,9 @@ > [!WARNING] > -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. +> The Optimization iOS SDK is in beta. Breaking changes can be published at any time. -The Optimization iOS SDK is a pre-release Swift Package for native iOS applications. It is part of +The Optimization iOS SDK is a beta Swift Package for native iOS applications. It is part of the [Contentful Optimization SDK Suite](../../README.md) and runs shared optimization behavior through the local JavaScriptCore bridge while Swift code owns native app concerns such as persistence, networking, lifecycle handling, SwiftUI views, and preview-panel UI. @@ -53,7 +53,7 @@ persistence, networking, lifecycle handling, SwiftUI views, and preview-panel UI [Entry personalization and variant resolution](../../documentation/concepts/entry-personalization-and-variant-resolution.md#single-locale-cda-entry-contract). For the broader locale model, see [Locale handling in the Optimization SDK Suite](../../documentation/concepts/locale-handling-in-the-optimization-sdk-suite.md). -- This surface is alpha implementation work. Treat the API, setup flow, and bridge contract as +- Treat this surface as beta-stage implementation work. The API, setup flow, and bridge contract are subject to change until a stable native iOS SDK release is declared. ## When to use this package diff --git a/packages/node/node-sdk/README.md b/packages/node/node-sdk/README.md index b4b09adb..62359f46 100644 --- a/packages/node/node-sdk/README.md +++ b/packages/node/node-sdk/README.md @@ -15,10 +15,6 @@ -> [!WARNING] -> -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. - The Optimization Node SDK implements stateless server-side optimization behavior on top of the [Optimization Core SDK](../../universal/core-sdk/README.md). Use it for server rendering, server functions, and Node services that need request-scoped profile evaluation or event emission. diff --git a/packages/node/node-sdk/package.json b/packages/node/node-sdk/package.json index d10ee391..a39668de 100644 --- a/packages/node/node-sdk/package.json +++ b/packages/node/node-sdk/package.json @@ -1,5 +1,6 @@ { "name": "@contentful/optimization-node", + "description": "Node.js SDK for Contentful Optimization", "version": "1.0.0", "license": "MIT", "repository": { diff --git a/packages/react-native-sdk/README.md b/packages/react-native-sdk/README.md index 876272da..266ec93f 100644 --- a/packages/react-native-sdk/README.md +++ b/packages/react-native-sdk/README.md @@ -17,7 +17,7 @@ > [!WARNING] > -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. +> The Optimization React Native SDK is in beta. Breaking changes can be published at any time. The Optimization React Native SDK provides a stateful mobile runtime on top of the [Optimization Core SDK](../universal/core-sdk/README.md). It adds React providers, hooks, diff --git a/packages/react-native-sdk/package.json b/packages/react-native-sdk/package.json index b6355336..f6366d2d 100644 --- a/packages/react-native-sdk/package.json +++ b/packages/react-native-sdk/package.json @@ -1,5 +1,6 @@ { "name": "@contentful/optimization-react-native", + "description": "React Native SDK for Contentful Optimization", "version": "1.0.0-beta.0", "license": "MIT", "repository": { diff --git a/packages/universal/api-client/README.md b/packages/universal/api-client/README.md index 9613c0a4..21b57e41 100644 --- a/packages/universal/api-client/README.md +++ b/packages/universal/api-client/README.md @@ -15,10 +15,6 @@ -> [!WARNING] -> -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. - The Contentful Optimization API Client provides low-level transport for the Experience API and Insights API. Application-facing SDKs compose this package with event builders, state management, queueing, and runtime-specific defaults. diff --git a/packages/universal/api-client/package.json b/packages/universal/api-client/package.json index 5c6408f6..01168a4d 100644 --- a/packages/universal/api-client/package.json +++ b/packages/universal/api-client/package.json @@ -1,5 +1,6 @@ { "name": "@contentful/optimization-api-client", + "description": "API client for Contentful Optimization services", "version": "1.0.0", "license": "MIT", "repository": { diff --git a/packages/universal/api-schemas/README.md b/packages/universal/api-schemas/README.md index e4a85bf3..74a7a281 100644 --- a/packages/universal/api-schemas/README.md +++ b/packages/universal/api-schemas/README.md @@ -15,10 +15,6 @@ -> [!WARNING] -> -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. - The Contentful Optimization API Schema Library provides Zod Mini schemas, inferred TypeScript types, and small runtime helpers for Contentful CDA, Experience API, and Insights API payloads. SDK layers use this package to validate API contracts and normalize optimization data. diff --git a/packages/universal/api-schemas/package.json b/packages/universal/api-schemas/package.json index ca926484..24de6322 100644 --- a/packages/universal/api-schemas/package.json +++ b/packages/universal/api-schemas/package.json @@ -1,5 +1,6 @@ { "name": "@contentful/optimization-api-schemas", + "description": "API schemas and types for Contentful Optimization", "version": "1.0.0", "license": "MIT", "repository": { diff --git a/packages/universal/core-sdk/README.md b/packages/universal/core-sdk/README.md index 70ab91e4..e4ee3072 100644 --- a/packages/universal/core-sdk/README.md +++ b/packages/universal/core-sdk/README.md @@ -15,10 +15,6 @@ -> [!WARNING] -> -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. - The Optimization Core SDK owns the platform-agnostic optimization state machine, event builders, queues, resolvers, and interceptors used by the application-facing SDKs. Web, React Web, Node, React Native, and native bridge layers build on this package. diff --git a/packages/universal/core-sdk/package.json b/packages/universal/core-sdk/package.json index 724a0f3e..d40fab49 100644 --- a/packages/universal/core-sdk/package.json +++ b/packages/universal/core-sdk/package.json @@ -1,5 +1,6 @@ { "name": "@contentful/optimization-core", + "description": "Platform-agnostic core SDK for Contentful Optimization", "version": "1.0.0", "license": "MIT", "repository": { diff --git a/packages/web/frameworks/nextjs-sdk/README.md b/packages/web/frameworks/nextjs-sdk/README.md index f5ba2e06..eae2b418 100644 --- a/packages/web/frameworks/nextjs-sdk/README.md +++ b/packages/web/frameworks/nextjs-sdk/README.md @@ -16,10 +16,6 @@ -> [!WARNING] -> -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. - `@contentful/optimization-nextjs` is a thin adapter for Next.js applications. It composes the Node SDK on the server with the React Web SDK on the client; it is not a new optimization runtime. The package root intentionally has no runtime export. Import one of the documented subpaths so the diff --git a/packages/web/frameworks/nextjs-sdk/package.json b/packages/web/frameworks/nextjs-sdk/package.json index 0dc193c0..e9075fca 100644 --- a/packages/web/frameworks/nextjs-sdk/package.json +++ b/packages/web/frameworks/nextjs-sdk/package.json @@ -1,5 +1,6 @@ { "name": "@contentful/optimization-nextjs", + "description": "Next.js adapter for Contentful Optimization", "version": "1.0.0", "license": "MIT", "repository": { diff --git a/packages/web/frameworks/react-web-sdk/README.md b/packages/web/frameworks/react-web-sdk/README.md index 65f1df46..a9575871 100644 --- a/packages/web/frameworks/react-web-sdk/README.md +++ b/packages/web/frameworks/react-web-sdk/README.md @@ -15,10 +15,6 @@ -> [!WARNING] -> -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. - The Optimization React Web SDK provides React providers, hooks, router adapters, and entry-rendering primitives on top of the [Optimization Web SDK](../../web-sdk/README.md). Use it when a React browser application must not manage the lower-level Web SDK instance, state subscriptions, entry diff --git a/packages/web/frameworks/react-web-sdk/package.json b/packages/web/frameworks/react-web-sdk/package.json index b239f3e3..11a58da6 100644 --- a/packages/web/frameworks/react-web-sdk/package.json +++ b/packages/web/frameworks/react-web-sdk/package.json @@ -1,5 +1,6 @@ { "name": "@contentful/optimization-react-web", + "description": "React SDK for Contentful Optimization", "version": "1.0.0", "license": "MIT", "repository": { diff --git a/packages/web/preview-panel/README.md b/packages/web/preview-panel/README.md index 4aa3d460..37806f4d 100644 --- a/packages/web/preview-panel/README.md +++ b/packages/web/preview-panel/README.md @@ -15,10 +15,6 @@ -> [!WARNING] -> -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. - This package implements the first-party browser preview panel for the [Optimization Web SDK](../web-sdk/README.md). It loads into the DOM as a Lit-based Web Component micro-frontend and talks to the Web SDK through the preview bridge exposed by the Optimization Web diff --git a/packages/web/preview-panel/package.json b/packages/web/preview-panel/package.json index ca40007b..f00d3017 100644 --- a/packages/web/preview-panel/package.json +++ b/packages/web/preview-panel/package.json @@ -1,5 +1,6 @@ { "name": "@contentful/optimization-web-preview-panel", + "description": "Preview panel UI for Contentful Optimization Web integrations", "version": "1.0.0", "license": "MIT", "repository": { diff --git a/packages/web/web-sdk/README.md b/packages/web/web-sdk/README.md index 86ee1d83..6c97f1b8 100644 --- a/packages/web/web-sdk/README.md +++ b/packages/web/web-sdk/README.md @@ -15,10 +15,6 @@ -> [!WARNING] -> -> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time. - This SDK implements browser-specific optimization behavior on top of the [Optimization Core SDK](../../universal/core-sdk/README.md). Use it directly for non-React browser applications, framework adapters, and client-side runtimes that need consent state, anonymous ID diff --git a/packages/web/web-sdk/package.json b/packages/web/web-sdk/package.json index 07d49abe..26e3329d 100644 --- a/packages/web/web-sdk/package.json +++ b/packages/web/web-sdk/package.json @@ -1,5 +1,6 @@ { "name": "@contentful/optimization-web", + "description": "Framework-agnostic Web client SDK for Contentful Optimization", "version": "1.0.0", "license": "MIT", "repository": { diff --git a/skills/optimization-guide-authoring/SKILL.md b/skills/optimization-guide-authoring/SKILL.md index 876de19b..7182667c 100644 --- a/skills/optimization-guide-authoring/SKILL.md +++ b/skills/optimization-guide-authoring/SKILL.md @@ -51,13 +51,6 @@ go deeper. Two consequences drive everything below: reads as if it were always this way. (A `## Troubleshooting` row describing a present symptom and its fix — e.g. a build error and how to resolve it — is current-state guidance, not history, and is fine.) -- **No SDK-version guidance while the SDK is pre-release/alpha.** With one moving version, do not - distinguish SDK versions, tell readers to "upgrade to the fixed version", or document - version-to-version deltas of _this SDK_ — there is no stable version surface to reason about yet. - Document the single current version in present tense. Revisit at the first major release, when - version differences become real to a reader. This applies only to _this SDK's_ versions; - host-framework version guidance (e.g. a Next.js 15 vs 16 filename/export the reader must choose - between today) is a present-state fact about the reader's environment and stays. ## Scope diff --git a/skills/sdk-knowledge-maintenance/SKILL.md b/skills/sdk-knowledge-maintenance/SKILL.md index 2566f13d..3670ab08 100644 --- a/skills/sdk-knowledge-maintenance/SKILL.md +++ b/skills/sdk-knowledge-maintenance/SKILL.md @@ -55,12 +55,6 @@ These are the transferable behaviors this skill exists to preserve. the fact in place_ so it reads as if it were always true — do not append a note about the change or strike through the old value. (Genuine runtime conditionals — "after reading headers the route cannot use ISR" — are present-tense behavior, not history, and are fine.) -- **While the SDK is pre-release/alpha, record no SDK-version deltas.** One moving version means - there is nothing to compare — do not note what a prior SDK version did, "upgrade to the fixed - version", or version-to-version differences of this SDK. Record the single current version's facts - in present tense. (Host-framework version facts the reader must act on today — e.g. a framework - that resolves a handler differently across its own major versions — are present-state environment - facts and are fine.) Revisit at the SDK's first major. - **Every fact carries a `source:` pointer in the grammar.** Pointers are machine-checked by `pnpm knowledge:check`; the grammar is defined in the base's own `README.md#source-pointer-grammar` and is symbol-anchored — `##` (plus `impl:`, `concept:`, `kb:`, `extern:`),