How to Contribute

Setup

git clone <repo-url>
cd antora-asciidoc-tracing
npm install
npm run build
npm test

Development workflow

npm run build          # Compile TypeScript (src/ → lib/)
npm test               # Run all tests (compiles test files first)
npm run test:coverage  # Run tests with c8 coverage
npm run lint           # Run biome checks
npm run format         # Auto-format with biome

Two TypeScript configurations:

  • tsconfig.json — production build: src/ → lib/

  • tsconfig.test.json — test build: src/ + test/ → lib/

The build script (scripts/build.js) copies templates, presets, and CJS extension files to lib/src/ for npm distribution.

Pre-commit hooks: biome lint + format and Vale prose lint via pre-commit.

Preview the example site

Build the full deployed site locally (Antora docs + blog + landing page + PDF + DOCX):

npm run preview    # same pipeline as CI, uses local content

This script (scripts/preview.js) replicates the CI pipeline in one command:

  1. Cleans public/

  2. Builds the Antora documentation site and blog (public/docs/)

  3. Generates PDFs and DOCX (public/pdf/) — skipped if ruby/pandoc is missing

  4. Copies the landing page (landing/ → public/)

After building, serve locally:

npx serve public

To serve the site in a container or add authentication, see Serve the site with Docker.

The CI workflow calls the same script with --ci to use the remote content source (antora-playbook-ci.yml) instead of the local one (antora-playbook.yml).

Blog

The blog is an Antora component (blog/) that renders alongside the docs. Posts are AsciiDoc files with :page-date: and :page-tags: attributes.

# Add a new post
cp blog/modules/ROOT/pages/2026-01-15-hello.adoc blog/modules/ROOT/pages/$(date +%Y-%m-%d)-my-post.adoc
# Edit content, update :page-date: and :page-tags:
node scripts/generate-blog-index.js    # Regenerate index page
npm run preview                        # Build and check locally

The index generator (scripts/generate-blog-index.js) scans blog/modules/ROOT/pages/*.adoc, extracts metadata, and writes index.adoc with a date-sorted listing. It’s called automatically by npm run preview and in CI.

Code style

  • TypeScript strict mode

  • ESM imports with .js extensions in import paths

  • JSDoc comments on public methods

  • No default exports (named exports only)

  • Biome for linting and formatting

Documentation style

Documentation follows the Documentation Style Guide — Diátaxis structure, one sentence per line, EARS requirements, and the voice rules there.

Commit conventions

This project follows Conventional Commits:

<type>(<scope>): <description>

Types: feat, fix, docs, style, refactor, test, chore, ci, perf

Common scopes: parser, cli, preset, matrix, neo4j, antora, config, graph

Testing

Tests use Mocha + Chai, written in TypeScript, compiled with tsconfig.test.json to lib/test/. Write tests:

import { expect } from 'chai';
import { RequirementsTraceabilityExtension } from '../src/index.js';

describe('MyFeature', () => {
  it('should do something', () => {
    const extension = new RequirementsTraceabilityExtension();
    extension.process(`...[#X, item, role=requirement]...`, { sourceFile: 'test.adoc' });
    expect(extension.getAllItems()).to.have.lengthOf(1);
  });
});

Run individual test files:

npx mocha 'lib/test/graph-and-api.test.js'

Build and release

The Antora component version is derived from the git refname, not hand-maintained: main is a named prerelease (version: main + prerelease: true) served at /main/, and each maintenance branch (vX.Y.x) carries a refname projection that derives its version. The playbook’s latest_version_segment: stable points /stable/ at the newest release.

A release touches package.json, CHANGELOG.md, and the CI playbook, then tags and branches:

npm run build          # Compile
npm test               # Verify all tests pass
npm version 0.7.0 --no-git-tag-version   # Bump version (no commit/tag yet)
# edit CHANGELOG.md and antora-playbook-ci.yml (branches: ['main', 'v0.7.x'])
git commit -am "chore(release): v0.7.0"
git tag v0.7.0
git checkout -b v0.7.x v0.7.0
# set the projection on the branch's antora.yml, commit, push
node scripts/release-check.js   # verify consistency
git push --follow-tags          # CI builds, tests, and publishes

Pushing the v0.7.0 tag triggers the release workflow, which stages the package with an npm provenance attestation and attaches a cosign-signed SBOM. A maintainer then approves the staged version to publish it:

npm stage list                    # find the stage id
npm stage approve <stage-id>      # prompt for 2FA, then publish

The same workflow stages @antora-tracer/id-server when its version changes.

Confirm a release with:

npm attestation verify @antora-tracer/core@0.7.0
cosign verify-blob --certificate-identity \
  https://github.com/rattermeyer/antora-tracer/.github/workflows/release.yml@refs/tags/v0.7.0 \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --bundle bom-core.json.bundle bom-core.json

The SBOM files (bom-core.json and its .bundle) are attached to the GitHub release.

See the publish skill for the complete checklist.

Related