# Release Checklist

This page captures the package-level checks that should pass before publishing or handing off a release candidate.

## Package Manager

Use Yarn Berry through Corepack.

```bash
corepack yarn --version
corepack yarn install --immutable
```

The repository uses Yarn 4 with strict Plug'n'Play (`nodeLinker: pnp`). Yarn
keeps ordinary JavaScript dependencies in its cache archives. Compiler,
proto-generation, and platform-native packages that require real executable
paths are selectively unplugged.

## Build

```bash
corepack yarn build
```

The build first produces the browser-neutral `@zyno-io/ts-reflection` workspace, then performs a clean TypeScript compile, builds the DevConsole assets, and makes compiled CLI files executable.

For local iteration:

```bash
corepack yarn build:dirty
```

## Tests

```bash
corepack yarn test
corepack yarn test-app
```

`test` builds the package and runs compiled `node:test` specs. `test-app` builds and runs the integration-style sample app under `test-app/`.

Database tests require local database services according to the testing config. See [Testing](./testing.md).

## Docs

```bash
corepack yarn docs:build
```

The generated VitePress output is written to `docs/.vitepress/dist/` and should not be committed as source.

## OpenAPI

For apps that generate clients from the schema, regenerate OpenAPI from the compiled app.

```bash
corepack yarn tsf-dev openapi:generate
```

This builds the app and invokes the package `main` with the built-in `openapi:generate` app command.

The runtime can also serve `/openapi.json` and `/openapi.yaml` when `ENABLE_OPENAPI_ROUTE=true`.

## Package Contents

The package publishes:

- `dist/src/`
- `dist/devconsole/`
- `docs/content/`
- `docs/.vitepress/config.mts`
- `docs/openapi.md`
- `resources/`
- `template-app/`
- `types.d.ts`
- `package.json`

`@zyno-io/ts-reflection` is published from `packages/reflection` with its own ESM and CommonJS runtime entrypoints, plus the CommonJS `/type-compiler` plugin. CI gives reflection and foundation the same release version, rewrites foundation's workspace dependency to that concrete version, then publishes reflection before foundation.

Foundation supports the root export, `/otel`, and compatibility subpaths for metadata runtime and the type compiler. The reflection package supports its root export plus `/type-metadata-runtime` and `/type-compiler`. Although `package.json` is included in either tarball, it is not exposed through the package `exports` map. See [Public API](./public-api.md).

## Local Pack Inspection

Use a dry run to inspect the tarball list.

```bash
yarn pack --dry-run
```

Confirm generated build outputs are present and local-only artifacts such as `docs/.vitepress/dist/` are absent unless intentionally published.

## Versioning Notes

CI derives release versions from the commit timestamp in UTC using `YY.MDD.HHmm`-style calendar versioning (for example, `26.711.1430` for July 11, 2026 at 14:30 UTC). Non-`main` builds append `-canary.<short-sha>`. Consumers that require reproducible behavior should pin an exact version rather than assuming semantic-version compatibility between calendar releases.

After GitLab publishes and mirrors a `main` commit, the GitHub `Release Type Compiler Prebuilds` workflow builds CGO-disabled prebuilds for the reflection package's type compiler on Linux, macOS, and Windows for x64 and arm64. It creates or updates the `v<package-version>` GitHub release with one binary and manifest per successful target. A failed target does not prevent other target assets from being released, and consumers always retain the packaged-source fallback.

Treat these as breaking changes:

- removing or renaming a root export
- changing package export paths
- changing HTTP parameter resolution semantics
- changing database migration output for existing annotations
- changing OpenAPI operation IDs or schema shapes
- changing CLI command names or required flags

Update docs in the same change as API behavior changes.