Development and release

Build, test, document, and release the SDK safely

  • Stable unknown
  • Release candidate since 1.16.1-rc.1
  • Development since 1.16.1-dev+97b2473

Repository layout

PathResponsibility
src/Published TypeScript/React Native source
example/Native Expo reference app and manual verification surface
doc/Docusaurus site
src/**/testsUnit and protocol tests (there is no top-level tests/ directory)
.github/workflows/ci.ymlPull request lint, typecheck, tests, native export, and docs build
.github/workflows/deliver.ymlAutomatic package releases after CI and manual example-app updates
.github/workflows/deployment-notes.ymlRecords deployment metadata for repository pushes
.github/workflows/sync-native-docs.ymlSyncs released React Native SDK docs into Actimi/ovok-docs
deployment-logs/Generated deployment notes; do not edit as documentation source

Local checks

Run the checks that match the change:

yarn lint
yarn build
yarn test
yarn prepare
yarn docs:generate
yarn docs:api:check
yarn doc build

yarn docs:generate refreshes the public API entry-point map, the API reference and the full LLM reference. yarn docs:api-reference regenerates doc/docs/reference/ with TypeDoc and fails when an exported symbol or prop has no doc comment; commit its output with the change, as AGENTS.md requires. yarn docs:api:check confirms the checked-in entry-point map matches package exports and source barrels. Documentation changes must also pass yarn doc build and git diff --check. Bluetooth or health changes also need protocol/service tests and physical-device verification where possible.

Version and publishing safety

The package version is stored in the root package.json. Documentation-only changes do not require a version bump. A push to development, staging, or main starts CI and creates the corresponding package release after CI succeeds. The manual Deliver workflow inputs are for example-app updates and builds.

BranchRelease versionDistribution
developmentX.Y.Z-dev.<commit count>+<sha>npm dev dist-tag
stagingX.Y.Z-rc.Nnpm next dist-tag
mainX.Y.Znpm latest dist-tag

npm stores a development build without its +<sha>, for example 1.16.1-dev.2082. The git tag and GitHub release keep the full version. Development and release-candidate builds also accept the @ovok/core pre-release on the matching dist-tag, so npm install @ovok/native@dev @ovok/core@dev resolves without peer conflicts. A development or release-candidate build of a version that is already released fails: bump package.json first.

Before merging a release change:

  1. Confirm the intended package version and @ovok/core peer range.
  2. Build the library and docs.
  3. Run the unit tests.
  4. Verify the generated package contents.
  5. After merge, verify the generated release and, when that branch publishes to npm, check the exact package version with npm view @ovok/native@<version> version.

Behavior changes, new public hooks, queue semantics, and native configuration changes must use a minor version. Patch releases must not change runtime behavior. If a native release raises its required @ovok/core range, publish the core package first, then update the native peer range and release the native package.

Release notes must call out behavior changes explicitly, including altered callback ordering, retry/idempotency rules, date restoration, background permissions, native configuration, peer dependencies, and any new required app setup. A docs-only change can remain unversioned when it does not change the published runtime contract.

Do not run a local release command casually: the configured release tool can create a git tag, GitHub release, and npm publication.

Documentation source of truth

The package export map, src/index.tsx, and module index files define the public entry points. The generated public API table records those paths; module descriptions and usage guidance remain maintained in the docs. Device support is defined by BUILT_IN_MODELS and its protocols. The example app is the reference for native configuration and provider composition. When a page claims an export or prop, verify it against those files before merging.

See also

Last updated on

On this page