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.

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

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:

corepack yarn build:dirty

Tests

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.

Docs

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.

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.

Local Pack Inspection

Use a dry run to inspect the tarball list.

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.