# Development and release

Canonical page: https://docs.ovok.com/native-sdk/guide/release-and-development

## Repository layout [#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 [#local-checks]

Run the checks that match the change:

~~~bash
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](https://github.com/Actimi/ovok-mobile-sdk/blob/development/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 [#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:

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 [#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 [#see-also]

- [Public API map](./public-api.md)
- [Architecture and lifecycle](./architecture.md)
