Publication overview

1.The shape of a publication¶

flowchart LR
    classDef input fill:#15446c,stroke:#0d2c47,color:#ffffff,stroke-width:2px;
    classDef pipeline fill:#f0f6fb,stroke:#2f7bb6,color:#14202c,stroke-width:1.5px;
    classDef output fill:#f7f9fb,stroke:#c8d2dd,color:#14202c,stroke-width:1.5px;

    MD["Spec source
Markdown, Word,
DocBook, LaTeX, ...
+ images + schemas"]:::input
    PIPE["Publication pipeline
quality gates
HTML + PDF render
ZIP bundle"]:::pipeline
    OUT["Published artifacts
docs.oasis-open.org/
<tc-name>/<spec>/<version>/<stage>/"]:::output

    MD -->|TC editor commits| PIPE
    PIPE -->|gates pass| OUT
    PIPE -.->|gates fail
build stops| MD

The TC owns the source. The pipeline owns the rendering. The published artifacts land at canonical, versioned URLs.

2.What you commit¶

You do not commit the generated HTML, PDF, or ZIP. The pipeline writes those.

2.1Which format am I publishing from?¶

A publication starts with the TC's request to TC Administration, and the package may arrive in whatever form the TC produces: fully rendered final artifacts, or authoritative source for the pipeline (or staff) to render. Whatever the intake form, the final published form must conform to the same rules — stage naming, template, quality gates — whatever the authoring format. That conformance is what pub-check checks.

3.What the pipeline does¶

For each publication run:

1. Pre-render checks. The source is read, structural issues are flagged, the build stops before rendering if anything is broken. See publication quality for what gets caught.
2. Render. Markdown becomes HTML via pandoc. The HTML becomes PDF. Local images are embedded into the HTML so the rendered HTML is a single self-standing file.
3. Post-render assertions. The generated PDF is inspected for known regression classes (duplicate cover title, leaked build-runner paths).
4. Bundle. The HTML, PDF, source MD, and any companion artifacts are packaged into a ZIP under the same publication directory.
5. Publish. All files land on docs.oasis-open.org under the canonical path, with CDN caches refreshed.

If any gate fails, the run stops and the offending check is reported back to the TC. Nothing partially-published reaches the public URL.

4.What lands at docs.oasis-open.org¶

For a Committee Specification Draft 01 of <spec-name> in version 1.0 of <tc-name>, the canonical URLs are:

docs.oasis-open.org/<tc-name>/<spec-name>/v1.0/csd01/
  ├── <spec-name>-v1.0-csd01.md     (authoritative)
  ├── <spec-name>-v1.0-csd01.html   (rendering)
  ├── <spec-name>-v1.0-csd01.pdf    (rendering)
  ├── <spec-name>-v1.0-csd01.zip    (bundle)
  ├── images/...                    (referenced assets)
  └── schema/...                    (companion artifacts, if declared)

docs.oasis-open.org/<tc-name>/<spec-name>/v1.0/
  ├── <spec-name>-v1.0.md           (latest-stage copy, persistent)
  ├── <spec-name>-v1.0.html
  └── <spec-name>-v1.0.pdf

The stage-specific path (csd01/, cs01/, os/, etc.) is the citable, immutable reference for that stage. The latest-stage path is a persistent shortcut that always points at whatever the latest published stage is.

5.What the TC controls¶

The TC owns four kinds of decisions:

The TC does not need to maintain the rendering toolchain, the pandoc filters, the wkhtmltopdf configuration, or the deployment pipeline. Those are operated by OASIS and refined behind the contract.

6.The contract¶

The pipeline guarantees, for every publication run:

• The source Markdown is preserved verbatim at the canonical URL alongside the renderings
• The HTML and PDF are byte-deterministic from the same source on the same toolchain version
• Quality gates catch known regression classes before publication, not after
• Published artifacts are immutable at their stage-specific URL; corrections require a new stage
• Cache layers are refreshed on every publication so the public URL serves the new version within minutes

The pipeline does not promise:

• Editorial review of spec content (that's the TC's responsibility, and OASIS Open's editorial process)
• Visual perfection of every edge case in author-supplied Markdown (the TC editor and the OASIS publication operator do the QA pass before final stage publication)
• Forward compatibility of the source MD with future renderer changes (major-version renderer changes are managed by the OASIS publication operator with deliberate migration)

7.Stage progression¶

A specification typically moves through these public publication stages over its lifecycle. The TC decides which stages it wants and when.

Each stage publication is its own immutable artifact at its own URL.

Retired stage tokens. csprd, cnprd, and cos were removed by Naming Directives v1.7 (2 January 2024). A document entering public review keeps its stage name: a CSD in review is still csd##, never csprd##. pub-check blocks the retired tokens at intake for every authoring format.

This site and the TC Handbook. The TC Handbook governs the process rules — review lengths, ballots, what each stage approval requires; this site documents the publication mechanics that carry those rules out. Where they appear to disagree, the Handbook and the TC Process win. Stage-specific rules: Public Review and Approving an OASIS Standard.

8.Where to next¶

• Getting started: onboarding a new TC for publication
• Publication configuration: the two-layer YAML config the TC can use to tune publication behaviour
• Publication quality: common publication issues and how the pipeline catches them
• TC Handbook: the process rules this site's mechanics serve
• Specification guidelines: the naming directives (v1.7 current) and naming guidelines that bind stage tokens, filenames, and URIs
• pub-check: the TC-side publication gate, both tracks — run it in your own build before the vote; TC Administration re-runs it identically at intake