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.tsandversion-numbering.tsdefine release-train and semantic-version behavior.release-automation.ts,release-candidates.ts, andstaged-rollouts.tsdefine gated execution and promotion flows.feature-gates.ts,rollback.ts,hotfix.ts, andsecurity-releases.tscover safe rollout, incident response, and security handling.lts-support.ts,end-of-life.ts,upgrade-paths.ts, andcompatibility-matrix.tsmodel lifecycle support obligations.
When you add a pipeline capability:
- Add or extend the module in
src/pipeline/. - Export it from
src/pipeline/index.tsandsrc/index.tswhen appropriate. - Add or expand Vitest coverage in
tests/pipeline.spec.ts. - Update the API reference and documentation coverage matrix.
Extending Distribution Features#
Distribution modules materialize operational release assets:
download-infrastructure.ts,cdn.ts, andmirror-network.tscover artifact delivery paths.checksum.tsandsignature.tshandle integrity and authenticity evidence.installer.ts,offline-installer.ts, andpackage-repos.tsgenerate installable release formats and repository metadata.auto-update.ts,delta-updates.ts, andenterprise-distribution.tscover update channels and managed deployment.site-licensing.ts,volume-licensing.ts,trial-versions.ts, andfreemium.tshandle 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.tsenforces budget compliance for the benchmark scenarios insrc/performance/release-benchmarks.ts.- The same benchmark suite also enforces the certified
< 5%regression gate against the stabilized baseline ledger insrc/performance/release-benchmarks.ts. tests/documentation.spec.tsenforces 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