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
| Path | Responsibility |
|---|---|
| src/ | Published TypeScript/React Native source |
| example/ | Native Expo reference app and manual verification surface |
| doc/ | Docusaurus site |
| src/**/tests | Unit and protocol tests (there is no top-level tests/ directory) |
| .github/workflows/ci.yml | Pull request lint, typecheck, tests, native export, and docs build |
| .github/workflows/deliver.yml | Automatic package releases after CI and manual example-app updates |
| .github/workflows/deployment-notes.yml | Records deployment metadata for repository pushes |
| .github/workflows/sync-native-docs.yml | Syncs 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 buildyarn 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.
| Branch | Release version | Distribution |
|---|---|---|
development | X.Y.Z-dev.<commit count>+<sha> | npm dev dist-tag |
staging | X.Y.Z-rc.N | npm next dist-tag |
main | X.Y.Z | npm 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:
- Confirm the intended package version and @ovok/core peer range.
- Build the library and docs.
- Run the unit tests.
- Verify the generated package contents.
- 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