https://github.com/calconnect/cc-template
GitHub repository template for CalConnect Metanorma document repositories
https://github.com/calconnect/cc-template
Last synced: 18 days ago
JSON representation
GitHub repository template for CalConnect Metanorma document repositories
- Host: GitHub
- URL: https://github.com/calconnect/cc-template
- Owner: CalConnect
- Created: 2026-05-25T02:55:15.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-26T06:42:14.000Z (about 1 month ago)
- Last Synced: 2026-05-26T08:29:59.666Z (about 1 month ago)
- Language: Ruby
- Size: 10.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.adoc
Awesome Lists containing this project
README
= cc-template
GitHub repository template for CalConnect Metanorma document repositories.
Supports single-publishing (CalConnect only) and dual-publishing (CalConnect + IETF).
== Quick start
. Click **Use this template** on GitHub to create a new repository (e.g. `cc-icalendar-series`).
. Replace `XXXXX` with the assigned document number:
* `sources/cc-XXXXX.adoc` → `sources/cc-51020.adoc`
* `metanorma.yml` → update the file list and collection name
. For IETF dual-publishing, rename `sources/draft-ietf-calext-example-00.adoc` to match your IETF draft name.
. Delete any files you don't need (IETF files if single-publishing, or vice versa).
. Write your document in AsciiDoc under `sources/`.
. Add the `metanorma-release` GitHub topic to the repository.
. Push to `main` — the `generate` workflow builds a preview, the `release` workflow publishes to standards.calconnect.org.
== Repository structure
=== Single-publishing (CalConnect only)
```
├── .github/workflows/
│ ├── generate.yml
│ └── release.yml
├── .gitignore
├── Gemfile
├── metanorma.yml
├── metanorma.release.yml
└── sources/
├── cc-XXXXX.adoc # CalConnect document
└── sections/ # Sections
```
=== Dual-publishing (CalConnect + IETF)
```
├── .github/workflows/
│ ├── generate.yml
│ └── release.yml
├── .gitignore
├── Gemfile
├── metanorma.yml # Lists both .adoc files
├── metanorma.release.yml # Only routes cc-* to channels
└── sources/
├── cc-XXXXX.adoc # CalConnect document (released)
├── draft-ietf-calext-example-00.adoc # IETF internet-draft (not released)
├── sections/ # Shared sections (abstract, intro, scope, terms)
│ ├── 00-abstract.adoc
│ ├── 01-intro.adoc
│ ├── 01-scope.adoc
│ ├── 02-normative-references.adoc
│ ├── 03-terms.adoc
│ └── 99-acknowledgements.adoc
└── sections-ietf/ # IETF-specific sections (conventions, references)
├── 02-conventions.adoc
└── 99-references.adoc
```
Both documents share sections from `sections/` (abstract, intro, scope, terms).
IETF-specific content goes in `sections-ietf/` (BCP 14 conventions, IETF-style references).
== Document types
Set the `:doctype:` attribute in your `.adoc` header:
[cols="1m,2,2",options="header"]
|===
|Doctype |Description |Display category
|`standard` |Normative standard |Standards, Specifications & Reports
|`specification` |Technical specification |Standards, Specifications & Reports
|`report` |Technical report |Standards, Specifications & Reports
|`guide` |Implementation guide |Guides & Advisories
|`advisory` |Advisory/recommendation |Guides & Advisories
|`directive` |Organizational directive |Directives
|`administrative` |Minutes, agendas, reports |Administrative
|`amendment` |Amendment to a standard |Amendments & Technical Corrigenda
|`technical-corrigendum` |Technical corrigendum |Amendments & Technical Corrigenda
|===
=== CalConnect document attributes
[source,adoc]
----
= CalConnect Standard: TODO Document Title
:title: TODO Document Title
:docnumber: XXXXX
:copyright-year: 2026
:language: en
:doctype: standard
:edition: 1
:status: working-draft
:revdate: 2026-01-01
:published-date: 2026-01-01
:technical-committee: CALENDAR
:fullname: TODO Author Name
:surname: TODO
:givenname: TODO
:affiliation: TODO Organization
:mn-document-class: cc
:mn-output-extensions: xml,html,pdf,rxl
:local-cache-only:
:data-uri-image:
----
Additional authors use `_2`, `_3` suffixes:
[source,adoc]
----
:fullname_2: Second Author
:surname_2: Author
:givenname_2: Second
:affiliation_2: Another Organization
----
=== IETF document attributes
[source,adoc]
----
= TODO Document Title
:doctype: internet-draft
:name: draft-ietf-calext-example-00
:status: standard
:ipr: trust200902
:area: Applications
:intended-series: full-standard
:revdate: 2026-01-01
:fullname: TODO Author Name
:lastname: TODO
:forename_initials: TODO
:affiliation: TODO Organization
:address: TODO Street + \
TODO City, TODO State TODO Code + \
TODO Country
:email: todo@example.com
:mn-document-class: ietf
:mn-output-extensions: xml,rfc,txt,html,rxl
:local-cache-only:
:data-uri-image:
----
Key differences from CalConnect documents:
* `:mn-document-class: ietf` — uses IETF formatting rules
* `:name:` — the IETF draft name (e.g. `draft-ietf-calext-valarm-extensions-01`)
* `:ipr:`, `:area:`, `:intended-series:` — IETF-specific metadata
* `:mn-output-extensions:` includes `rfc` and `txt`, not `pdf`
* Author format uses `:lastname:` / `:forename_initials:` instead of `:surname:` / `:givenname:`
* Author format includes `:address:` and `:email:` fields
== Channel routing
`metanorma.release.yml` controls which documents are released.
Only CalConnect documents (`cc-*`) are released to channels —
IETF internet-drafts are published through the IETF process, not via metanorma-release.
[source,yaml]
----
documents:
- pattern: "cc-*"
channels: [public/standards]
----
For a multi-doctype repository with separate channels:
[source,yaml]
----
documents:
- pattern: "cc-s-*"
channels: [public/standards]
- pattern: "cc-r-*"
channels: [public/reports]
- pattern: "cc-a-*"
channels: [public/admin]
----
== Stages
Set the `:status:` attribute to control the publication stage:
[cols="1m,1,2",options="header"]
|===
|Status |Stage code |Description
|`working-draft` |20 |Initial working draft
|`committee-draft` |30 |Committee review draft
|`draft-standard` |40 |Draft standard
|`final-draft` |50 |Final draft for public review
|`published` |60 |Published document
|===
The release workflow publishes all stages by default.
Draft stages are released as GitHub pre-releases.
The aggregator site can optionally include or exclude drafts via `include_drafts` in its config.
== CI workflows
=== `generate.yml` — Preview
Builds the Metanorma output on every push and PR.
Uses the reusable workflow from `actions-mn/.github`.
=== `release.yml` — Publication
Triggers on pushes to `main` that modify files under `sources/`, `metanorma.yml`, or `metanorma.release.yml`.
Supports manual dispatch with options:
* `include-pattern` — glob to filter which documents to release
* `force` — re-release even if content is unchanged
== Local development
[source,sh]
----
bundle install
bundle exec metanorma site generate --agree-to-terms
----
The generated output appears in `_site/`.
== Publishing to standards.calconnect.org
No manual steps needed.
The https://github.com/CalConnect/standards.calconnect.org[aggregator site] discovers repositories by the `metanorma-release` GitHub topic and subscribes to their release channels.
As long as your repo:
. Belongs to the `CalConnect` organization
. Has the topic `metanorma-release`
. Has a `metanorma.release.yml` with channel patterns
...it will be automatically aggregated and published on https://standards.calconnect.org.