Eve library

Neith Release Developer Guide

Guide

Revision 1

On this page

This guide is for contributors extending @neith/release.

Package Layout#

text
libs/neith/release/
  src/
    pipeline/      release authoring, rollout, and lifecycle logic
    distribution/  artifact hosting, integrity, update, and licensing flows
    platform/      packaging and store/marketplace publishing helpers
    performance/   benchmark scenarios and budget reports
    types.ts       shared release-domain types
    index.ts       public package surface
  tests/
    *.spec.ts      package verification, including documentation coverage

Development Rules#

  • Keep modules pure and data-driven where possible. Most package APIs generate plans, manifests, commands, or reports rather than performing network I/O.
  • Prefer deterministic outputs. Tests depend on stable artifact names, generated commands, and release workflow text.
  • Preserve semantic versioning guarantees for exported types and classes.
  • When adding a new module, update the relevant barrel export, external docs, and the coverage audit in docs/domains/neith/release/documentation-coverage.md.

Extending Pipeline Features#

Pipeline modules model release control-plane concerns:

  • branching-strategy.ts and version-numbering.ts define release-train and semantic-version behavior.
  • release-automation.ts, release-candidates.ts, and staged-rollouts.ts define gated execution and promotion flows.
  • feature-gates.ts, rollback.ts, hotfix.ts, and security-releases.ts cover safe rollout, incident response, and security handling.
  • lts-support.ts, end-of-life.ts, upgrade-paths.ts, and compatibility-matrix.ts model lifecycle support obligations.

When you add a pipeline capability:

  1. Add or extend the module in src/pipeline/.
  2. Export it from src/pipeline/index.ts and src/index.ts when appropriate.
  3. Add or expand Vitest coverage in tests/pipeline.spec.ts.
  4. Update the API reference and documentation coverage matrix.

Extending Distribution Features#

Distribution modules materialize operational release assets:

  • download-infrastructure.ts, cdn.ts, and mirror-network.ts cover artifact delivery paths.
  • checksum.ts and signature.ts handle integrity and authenticity evidence.
  • installer.ts, offline-installer.ts, and package-repos.ts generate installable release formats and repository metadata.
  • auto-update.ts, delta-updates.ts, and enterprise-distribution.ts cover update channels and managed deployment.
  • site-licensing.ts, volume-licensing.ts, trial-versions.ts, and freemium.ts handle commercial packaging strategies.

Prefer composable data structures over embedding platform policy into tests.

Extending Platform Publishing#

Each module in src/platform/ represents a publishing target or packaging surface. Keep interfaces platform-specific and keep generated command lists or manifest objects explicit so downstream automation can inspect them.

The web module is special because it also owns:

  • cache and security-header defaults
  • WCAG 2.1 AA accessibility auditing
  • accessibility statement generation

Any change to the web distribution surface should extend tests/platform.spec.ts.

Performance And Documentation Gates#

  • tests/performance.benchmark.spec.ts enforces budget compliance for the benchmark scenarios in src/performance/release-benchmarks.ts.
  • The same benchmark suite also enforces the certified < 5% regression gate against the stabilized baseline ledger in src/performance/release-benchmarks.ts.
  • tests/documentation.spec.ts enforces source-file documentation coverage and validates doc links in the release docs hub.

Keep both gates green before merging.

Local Workflow#

bash
pnpm nx run @neith/release:typecheck
pnpm nx run @neith/release:lint
pnpm nx run @neith/release:test
pnpm nx run @neith/release:benchmark

For documentation changes, also check formatting:

bash
pnpm exec prettier --check \
  docs/domains/neith/README.md \
  docs/domains/neith/release/**/*.md \
  libs/neith/release/README.md