CalConnect administrative documents

This repository contains CalConnect administrative document sources.

Published documents are available here:

• CalConnect Conference and IOP Testing Reports

Purpose

This repository holds the Metanorma source markup for CalConnect administrative documents.

These documents include:

• CalConnect Conference Reports (and associated documents)

• CalConnect IOP Testing Reports

• CalConnect Advisory Notices

Note	These administrative documents, prior to 2024, were published in PDF format only. This repository contains the re-encoded documents in the Metanorma format in order to facilitate future updates and publication in multiple formats.

Structure

The repository is structured as follows:

metanorma.yml

Metanorma site manifest that lists the documents to be included in the site.

sources/

Source documents in Metanorma format.

sources/cc-{docnumber}-{title}

Directory for each document, named by document number and a shorthand title.

sources/cc-{docnumber}-{title}/document.adoc

Metanorma root document for the document.

Fetching the document

git clone https://github.com/CalConnect/cc-admin-documents/

Installing build tools

See https://www.metanorma.org/install/

Building the documents

Full set

Run the following command to build the full collection of the documents.

$ bundle exec metanorma site generate --agree-to-terms

Single document

Run the following command to build a single document.

Compile a single document

$ bundle exec metanorma sources/cc-1903-report-conference-46/document.adoc

Outputs

The following outputs will be built:

Index of all documents

_site/index.html

Individual document outputs

_site/documents/ (HTML, PDF, MN XML)

Releasing documents

Documents are released as per-document GitHub Releases using the Release workflow. Each document is identified by its normalized docidentifier (derived from the RXL metadata: lowercased, non-alphanumeric characters replaced with hyphens). For example, CC/A 0402:2004 becomes cc-a-0402-2004.

A release is triggered automatically when source files change on main, or manually via workflow dispatch.

Automatic release

Push changes to sources/**, metanorma.yml, or metanorma.release.yml on main. The workflow compiles all documents and releases only those whose compiled output has changed (detected via content hashing).

Manual release (all documents)

Go to Actions → Release → Run workflow and click Run workflow with the defaults. This re-evaluates all documents but only re-releases those with changed content.

Manual release (specific documents)

Go to Actions → Release → Run workflow and set include-pattern to match the document’s normalized identifier. The pattern uses minimatch glob syntax and is matched against the identifier extracted from each document’s RXL file. For example:

Pattern	Matches
cc-a-1903*	All documents with docnumbers starting with 1903
cc-a-0904*	The document CC/A 0904:2009 (xCal)
0402	The document CC/A 0402:2004 (IOP test results)
roundtable	No match (pattern filters by identifier, not directory name)

Tip	To find a document’s identifier, check the :docnumber: attribute in its document.adoc. The normalized identifier follows the pattern cc-a-{docnumber}-{copyright-year}.

Force re-release

Check force in the workflow dispatch form to release matching documents even if their content hash is unchanged (e.g. after a Metanorma version update). Existing published releases are immutable and will not be overwritten; only draft releases are updated in-place.

Controlling visibility

Create a metanorma.release.yml file to control which documents are released publicly:

documents:
  - source: sources/cc-1903-report-conference-46/document.adoc
  - source: sources/cc-1902-report-conference-45/document.adoc
    visibility: private

When this file is absent, all documents are released.

License

Copyright CalConnect.