Delivery Process

This document captures the delivery process requirements — the CI/CD pipeline, quality gates, and release process that ensure the extension is built, tested, and deployed consistently. Each process requirement traces to the product requirements it validates and the architectural decisions it implements.

Continuous Integration

PRQ-001 — CI workflows trigger on push and PR

The GitHub Actions CI workflow SHALL trigger on every push to main and every pull request. The workflow SHALL run on the latest Ubuntu runner and SHALL execute npm ci, npm run build, npm test, and npm run lint in sequence.

The CI pipeline ensures that every change is validated against the full test suite before it reaches users — no manual testing step required.

Considered by
PRQ-002 — Test suite runs as merge gate

The test suite SHALL run as a required status check before merging any pull request to main. The suite SHALL include 275+ tests covering the extension core, Antora integration, CLI, matrix generation, Neo4j export, and link substitution. Any test failure SHALL block the merge.

Validates
Considered by
PRQ-003 — Example site builds without errors

The example site SHALL build successfully as part of the CI pipeline. The build SHALL include the Antora HTML site generation and PDF output. Any xref warnings or build errors SHALL be treated as failures.

The site build exercises the full extension pipeline — parsing, macro expansion, link substitution, matrix generation, and matrix registration in the content catalog — serving as an integration test.

Considered by

Deployment

PRQ-004 — Example site deploys from main branch

The example site SHALL deploy to GitHub Pages automatically on every push to main. The Pages workflow SHALL build the Antora site, generate PDFs, copy the landing page, and deploy to the gh-pages branch. The deployment SHALL be atomic — either all artifacts deploy or none.

The deployed site serves as the project’s public documentation and a live demonstration of the extension’s capabilities.

Validates
Considered by

Release

PRQ-005 — Release is tagged and versioned

Every release SHALL be tagged with a semver tag (v0.12.1) and the version SHALL be updated in package.json. The CHANGELOG SHALL be updated with all notable changes since the previous release. The release SHALL be published to npm.

Versioning follows Semantic Versioning: MAJOR for breaking API changes, MINOR for new features, PATCH for bug fixes and internal refactoring.

Considered by
PRQ-006 — PDF artifacts are generated alongside HTML

The Pages workflow SHALL generate PDF artifacts for the requirements, architecture, and test-plan documents using @antora/pdf-extension with Ruby and asciidoctor-pdf. PDFs SHALL be placed alongside HTML output in the deployed site.

The PDF pipeline is provisioned by devbox.json (Node.js + Ruby) and Gemfile (asciidoctor-pdf), ensuring reproducible builds across environments.

Validates
Considered by