Getting started

1.Audience¶

This page is for the person setting up a new TC's publication path for the first time, or migrating an existing TC onto the current pipeline. It is not a guide to editing or writing your specification. The TC editor sees publication overview and publication configuration instead.

2.Prerequisites¶

Before publication can happen, the TC needs:

If the TC is brand new, OASIS bootstraps the publication repository, the publication workflows, and the directory layout. The TC does not provision any of this itself.

3.First publication walkthrough¶

The TC editor produces a Markdown source. The OASIS publication operator handles the rest. The full first-publication walkthrough looks like this from the TC chair's point of view:

1. Spec source ready. TC editor pushes the Markdown source (plus any images and machine-readable artifacts) to the editorial source repository.
2. Date and stage agreed. TC chair and OASIS publication operator agree the publication date (typically the date of the TC approval vote) and stage code (csd01, cs01, os, etc.).
3. Pre-flight check. OASIS publication operator runs the build steps as a dry run and then the acceptance check, which changes nothing. The publication checks either pass or name a specific defect for the TC editor to fix. Iterate until clean. The TC editor can run the same acceptance checks (pub-check) in the TC's own build before the vote.
4. Stage publication. OASIS publication operator runs the publication steps, ending with go-live, which runs the acceptance checks again before anything is copied. The source MD, generated HTML, generated PDF, ZIP bundle and manifests land at the canonical stage URL. Caches refresh.
5. Verification. TC chair and at least one TC editor verify the published artifacts on docs.oasis-open.org. Citation block, links, images, schemas, and any companion artifacts are confirmed to resolve correctly.
6. Announcement. OASIS Open announces the new publication through its standard channels. The TC's own communication channels follow.

Subsequent stage publications follow the same shape with the publication operator running the chain.

4.Guidance for TC editors¶

The TC editor is responsible for the source. Practical guidance:

• Write in Markdown. The toolchain accepts pandoc-flavoured Markdown with fenced code blocks, tables, footnotes, and inline HTML where needed
• Reference images with relative paths under an images/ sibling directory
• If your spec declares machine-readable companion artifacts (JSON Schemas, XSDs, WSDLs), include them in the publication directory and reference them from the spec text with their final stage URL
• Citation block: follow the OASIS template. The publication operator may make small editorial corrections to the citation block at publication time (typos, stage URL alignment) and will log them back to the TC for the next working draft
• Expect step 1.0 to reformat your Markdown with Prettier and commit the result, so take the formatted copy as the base for the next working draft
• Keep images under 2 MB each and 5 MB in total; at the default limits a larger image stops the build. If one diagram has to be larger, say so in the publication request. See publication configuration

The TC editor does not need to run pandoc, the PDF renderers, the pre-PDF checks, the post-PDF checks, or anything else on the toolchain side. Those are the OASIS publication operator's concern.

5.Guidance for TC chairs¶

The TC chair sets policy. Practical guidance:

• Raise any TC-wide publication preference, such as a citation convention, with TC Administration. The toolkit has no per-TC configuration file; see publication configuration
• Put each publication to the TC for its vote (a Full Majority Vote for a Committee Specification Draft or to open a public review, a Special Majority Vote for a Committee Specification) and send the result to TC Administration before the publication operator runs the chain
• Verify each publication after it lands at docs.oasis-open.org

6.Corrections after publication¶

Published files are never edited (Naming Directives sections 6.3 and 6.4). After publication, TC Administration can make only three kinds of repair:

• add a file that should have been published and is missing;
• restore a published file from the publication repository when the copy being served differs from what the TC approved;
• forward a broken address at the edge to the correct published file, without changing any file.

Any other correction, however small (a typo in a citation URL, a wrong figure), needs a new revision at the same stage (csd01 becomes csd02; Naming Directives section 5.3), approved by the TC. Approved Errata apply only to an OASIS Standard. The TC chair raises a suspected defect with TC Administration, which says which route applies.

7.Related documentation¶

• Publication overview: what publication looks like from inside the pipeline
• Publication configuration: the rendering settings and who can change them
• Publication quality: common issues and how the pipeline catches them