diff --git a/doc/main.html b/doc/main.html index 0820e8e..17cca6c 100644 --- a/doc/main.html +++ b/doc/main.html @@ -18,8 +18,711 @@
-

This is the scope. See https://doc.smpte-doc.org/html-pub/main/ for documentation on how to use this template.

+

This document describes the process and workflow for the development and publication of SMPTE Engineering Documents using the GitHub-based authoring tooling defined in .

+
+ +
+ +
+ +
+

Mapping meta tags to Document Status

+

+ maps the required content values of pubState, pubStage, and pubConfidential as defined in during the various stages of document development. These values represent the naming convention(s) as defined in and flowcharts as defined in +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mapping content values for meta tags to Document Status
Document StatuspubStage valuepubState valuepubConfidential valueSee
Initial draft or revision (Working Draft) in: +
Draft Group (DG) +
Study Group (SG) +
Working Group (WG)		WDdraftyes
>> Document moves to TC >>
Pre-FCD (Final Committee Draft) reviewWDpubyes
>> If pre-FCD comments received, back to DG/SG/WG >>
Pre-FCD comment resolution ongoing CDdraftyes
Pre-FCD comment resolution complete CDpubyes
>> Document moves to TC >>
PCD (Public Committee Draft) periodCDpubno
PCD comment resolution ongoing (moves back to DG/SG/WG)CDdraftyes
PCD comment resolution complete>> Back to Pre-FCD (Final Committee Draft) review >>
(OR)
Ready for FCD ballotCDpubyes
FCD ballot periodCDpubyes
>> If FCD ballot comments received >>
FCD ballot comment resolution ongoingFCDdraftyes
FCD ballot comment resolution completeFCDpubyes
Pre-DP (Draft Publication) reviewFCDpubyes
DP ballot periodFCDpubyes
(ELSE)
FCD ballot passes, no commentsDPpubyes
DP ballot passesDPpubyes
Ready for ST (Standards Committee) AuditDPpubyes
ST Audit periodDPpubyes
ST Audit completePUBdraftyes
Waiting for publicationPUBdraftyes
PublishedPUBpubno
+ +

+ See for the workflow utilizing these statuses. +

+ +
+ +
+

GitHub PR (Pull Request) Guidelines

+ +

Changes to a document shall not be made directly on the main branch. All changes shall be made on a separate branch and merged to main via a Pull Request, so that the tooling can produce the required redlines (see ).

+ +

Each PR shall have at least one approver who is not the PR author. Approval requirements that vary by document stage are specified in .

+ +
+ +
+

Document Workflow

+ +
+

General

+ +

At any moment, a document is in one of the statuses listed in . The document's pubState, pubStage, and (during the PCD period) pubConfidential metadata values determine which one, as defined in .

+ +

A pub status (pubState=pub) lives on main, marked by an auto-drafted release. A draft status (pubState=draft) lives on a feature branch with an open Pull Request, which is the work container for that status — the PR accumulates commits while work is ongoing, and the tooling generates redlines on each PR build per . The document advances by merging that PR to main; merges that result in pubState=pub trigger the tooling to auto-draft a release per .

+ +

Each status is described below in a card with the same fields: Description, Metadata, Branch, Latest release, Redline, and Notification. After the fields, each card lists numbered procedures for entering and leaving the status, following . Each procedure step that requires a specific role is tagged with the role identifier defined in ; steps without a role tag (such as merging the PR or publishing the auto-drafted release) may be performed by any party with appropriate permissions.

+ +

Editors and Chairs should be aware of the general guidelines provided in .

+
+ +
+

Roles

+ +

Roles are as defined by . The identifiers below are used in this clause to tag procedure steps with the responsible role.

+ +
+
Document editor
+
The person designated by the project to edit the document.
+ +
DG chair
+
The chair of the Drafting Group, Study Group, or Working Group developing the document.
+ +
TC chair
+
The chair (or one of the chairs) of the parent Technology Committee.
+ +
GitHub admin
+
The person responsible for repository administration per .
+ +
SMPTE HO
+
SMPTE Headquarters Office, including the Director of Engineering.
+
+
+ +
+

WD-draft — Initial draft / DG drafting

+
+
Description
+
Drafting work in DG / SG / WG. Both initial drafts and revisions begin here.
+
Metadata
+
pubState=draft, pubStage=WD, pubConfidential=yes
+
Branch
+
YYYY-initial-draft (new document) or YYYY-revision (revising), branched from main
+
Latest release
+
None for an initial draft. For a revision, the prior YYYYMMDD-pub release of the previous edition.
+
Redline
+
pub-rl.html versus the prior published edition (revisions only)
+
Notification
+
None — internal DG iteration.
+
+ +

Entering this status:

+ +

For an initial draft:

+
    +
  1. GitHub admin: Set up the document repository per .
    2. +
  2. Document editor: Branch YYYY-initial-draft from main.
    3. +
  3. Document editor: On the new branch, set pubState=draft, pubStage=WD, and pubConfidential=yes per .
    4. +
  4. Document editor: Add the initial draft content.
    5. +
  5. Document editor: Open a Pull Request from the branch to main. The PR build generates redlines per .
    6. +
  6. The document is now in WD-draft. Drafting work continues as additional commits to this open PR.
    7. +
+ +

For a revision:

+
    +
  1. Document editor: Identify the prior published release tag YYYYMMDD-pub.
    2. +
  2. Document editor: Branch YYYY-revision from main (which contains the prior published state).
    3. +
  3. Document editor: On the new branch, set pubState=draft, pubStage=WD, and pubConfidential=yes per .
    4. +
  4. Document editor: Make the initial revision changes.
    5. +
  5. Document editor: Open a Pull Request from the branch to main. The PR build generates redlines including pub-rl.html versus the prior published edition.
    6. +
  6. The document is now in WD-draft. Revision work continues as additional commits to this open PR.
    7. +
+ +

Leaving this status:

+ +

When the DG declares drafting complete:

+
    +
  1. Document editor: On the open PR, set pubState=pub.
    2. +
  2. Document editor: Set pubDateTime to the date drafting was completed (format: YYYY-MM-DD).
    3. +
  3. DG chair: Reviews and approves the PR.
    4. +
  4. Merge the PR to main. The tooling auto-drafts a YYYYMMDD-wd release.
    5. +
  5. Publish the auto-drafted release per .
    6. +
  6. DG chair: Notifies the TC chair the document is ready for Pre-FCD review.
    7. +
  7. TC chair: Requests/starts Pre-FCD review from SMPTE HO.
    8. +
  8. The document is now in .
    9. +
+
+ +
+

WD-pub — Pre-FCD TC review

+
+
Description
+
2-week TC review of the completed Working Draft.
+
Metadata
+
pubState=pub, pubStage=WD, pubConfidential=yes
+
Branch
+
Status lives on main.
+
Latest release
+
YYYYMMDD-wd
+
Redline
+
release-rl.html versus the prior dated release (when present)
+
Notification
+
The TC chair sends the release link to the TC for the 2-week pre-FCD review.
+
+ +

Leaving this status:

+ +

If pre-FCD comments are received:

+
    +
  1. Document editor: Branch YYYYMMDD-cd1 from main.
    2. +
  2. Document editor: On the new branch, set pubState=draft and pubStage=CD.
    3. +
  3. Document editor: Open a Pull Request from the new branch to main. The PR is the work container for the next status; do not merge yet.
    4. +
  4. The document is now in . Comment resolution work happens as additional commits to this open PR; the PR is merged when leaving CD-draft.
    5. +
+ +

If no pre-FCD comments are received:

+
    +
  1. Document editor: Branch YYYYMMDD-cd1 from main.
    2. +
  2. Document editor: On the new branch, set pubState=pub and pubStage=CD.
    3. +
  3. Document editor: Open a Pull Request from the new branch to main.
    4. +
  4. DG chair: Reviews and approves the PR.
    5. +
  5. Merge the PR to main. The tooling auto-drafts a YYYYMMDD-cd1 release.
    6. +
  6. Publish the auto-drafted release per .
    7. +
  7. The document is now in .
    8. +
+
+ +
+

CD-draft — CD comment resolution

+
+
Description
+
Comment resolution — either pre-FCD comments from the TC or PCD comments from the public period.
+
Metadata
+
pubState=draft, pubStage=CD, pubConfidential=yes
+
Branch
+
YYYYMMDD-cdn from main (n increments per iteration: cd1, cd2, …)
+
Latest release
+
The prior YYYYMMDD-wd or YYYYMMDD-cdn-1 release.
+
Redline
+
release-rl.html versus the prior CD or WD release
+
Notification
+
None.
+
+ +

Leaving this status:

+ +

When comment resolution is complete:

+
    +
  1. Document editor: On the open comment-resolution PR, set pubState=pub.
    2. +
  2. Document editor: Set pubDateTime to the date resolution was completed (format: YYYY-MM-DD).
    3. +
  3. DG chair: Reviews and approves the PR.
    4. +
  4. Merge the PR to main. The tooling auto-drafts a YYYYMMDD-cdn release.
    5. +
  5. Publish the auto-drafted release per .
    6. +
  6. The document is now in .
    7. +
+
+ +
+

CD-pub — Committee Draft (private)

+
+
Description
+
A CD release awaiting next steps. Covers Pre-FCD comment resolution complete and Ready for FCD ballot at the same metadata.
+
Metadata
+
pubState=pub, pubStage=CD, pubConfidential=yes
+
Branch
+
Status lives on main.
+
Latest release
+
YYYYMMDD-cdn
+
Redline
+
release-rl.html
+
Notification
+
None.
+
+ +

Leaving this status:

+ +

If the document is to undergo a PCD (Public Committee Draft) period:

+
    +
  1. Document editor: Branch from main.
    2. +
  2. Document editor: On the new branch, set pubConfidential=no.
    3. +
  3. Document editor: Open a Pull Request from the new branch to main.
    4. +
  4. DG chair: Reviews and approves the PR.
    5. +
  5. If the merge will occur on the same calendar day as the prior YYYYMMDD-cdn release, include [force-release] in the merge commit message per .
    6. +
  6. Merge the PR to main. The tooling auto-drafts a release (with a -2, -3, … suffix when [force-release] was used).
    7. +
  7. Publish the auto-drafted release per .
    8. +
  8. DG chair: Notifies the TC chair the document is ready for PCD.
    9. +
  9. TC chair: Requests PCD publication from SMPTE HO.
    10. +
  10. SMPTE HO: Publishes PCD.
    11. +
  11. The document is now in .
    12. +
+ +

If the document is to undergo a FCD (Final Committee Draft) ballot:

+
    +
  1. DG chair: Notifies the TC chair the document is ready for FCD Ballot.
    2. +
  2. TC chair: Requests/starts FCD ballot from SMPTE HO.
    3. +
  3. The document is now in .
    4. +
+
+ +
+

CD-pub-public — PCD period (public)

+
+
Description
+
Public Committee Draft period. The CD release is made publicly available; pubConfidential reflects this.
+
Metadata
+
pubState=pub, pubStage=CD, pubConfidential=no
+
Branch
+
Status lives on main.
+
Latest release
+
The release auto-drafted on entry — typically the same YYYYMMDD-cdn tag as the originating release, possibly with a numeric suffix if [force-release] was used (see ).
+
Redline
+
release-rl.html (unchanged from CD-pub)
+
Notification
+
SMPTE HO announces the PCD period to the public.
+
+ +

Leaving this status:

+ +

When the PCD period ends:

+
    +
  1. Document editor: Branch YYYYMMDD-cdn+1 from main.
    2. +
  2. Document editor: On the new branch, set pubState=draft, pubStage=CD, and pubConfidential=yes.
    3. +
  3. Document editor: Open a Pull Request from the new branch to main. The PR is the work container for the next status; do not merge yet.
    4. +
  4. The document is now in — back to Pre-FCD (Final Committee Draft) review. Any PCD comments are addressed as additional commits to this open PR; the PR is merged when leaving CD-draft.
    5. +
+
+ +
+

FCD-ballot — FCD ballot period

+
+
Description
+
The TC conducts the FCD ballot. The outcome determines whether the document advances directly to Draft Publication or returns for FCD comment resolution.
+
Metadata
+
pubState=pub, pubStage=CD, pubConfidential=yes
+
Branch
+
Status lives on main.
+
Latest release
+
YYYYMMDD-cdn
+
Redline
+
release-rl.html
+
Notification
+
The TC chair sends the release link to the TC for the FCD ballot.
+
+ +

Leaving this status:

+ +

If the FCD ballot received comments:

+
    +
  1. Document editor: Branch YYYYMMDD-fcd-cr from main.
    2. +
  2. Document editor: On the new branch, set pubState=draft and pubStage=FCD.
    3. +
  3. Document editor: Open a Pull Request from the new branch to main. The PR is the work container for the next status; do not merge yet.
    4. +
  4. The document is now in . Comment resolution work happens as additional commits to this open PR; the PR is merged when leaving FCD-draft.
    5. +
+ +

If the FCD ballot passed without comments:

+
    +
  1. TC chair: Requests DP/ST Audit package from DG.
    2. +
  2. Document editor: Branch YYYYMMDD-dp from main.
    3. +
  3. Document editor: On the new branch, set pubStage=DP. (pubState remains pub.)
    4. +
  4. Document editor: Open a Pull Request from the new branch to main.
    5. +
  5. DG chair: Reviews and approves the PR.
    6. +
  6. Merge the PR to main. The tooling auto-drafts a YYYYMMDD-dp release.
    7. +
  7. Publish the auto-drafted release per .
    8. +
  8. The document is now in .
    9. +
+
+ +
+

FCD-draft — FCD ballot comment resolution

+
+
Description
+
Resolving comments raised during the FCD ballot.
+
Metadata
+
pubState=draft, pubStage=FCD, pubConfidential=yes
+
Branch
+
YYYYMMDD-fcd-cr (or similarly named comment-resolution branch) from main
+
Latest release
+
The prior YYYYMMDD-cdn release (the FCD ballot zip).
+
Redline
+
release-rl.html versus the prior CD release
+
Notification
+
None.
+
+ +

Leaving this status:

+ +

When comment resolution is complete:

+
    +
  1. Document editor: On the open comment-resolution PR, set pubState=pub.
    2. +
  2. Document editor: Set pubDateTime to the date resolution was completed (format: YYYY-MM-DD).
    3. +
  3. DG chair: Reviews and approves the PR.
    4. +
  4. Merge the PR to main. The tooling auto-drafts a YYYYMMDD-fcd release.
    5. +
  5. Publish the auto-drafted release per .
    6. +
  6. DG chair: Notifies the TC chair the document is ready for Pre-DP review.
    7. +
  7. TC chair: Requests/starts Pre-DP review from SMPTE HO.
    8. +
  8. The document is now in .
    9. +
+
+ +
+

FCD-pub — Pre-DP review

+
+
Description
+
FCD comments resolved; the TC reviews the document before the DP ballot is called. Covers FCD comment resolution complete and Pre-DP review at the same metadata.
+
Metadata
+
pubState=pub, pubStage=FCD, pubConfidential=yes
+
Branch
+
Status lives on main.
+
Latest release
+
YYYYMMDD-fcd
+
Redline
+
release-rl.html versus the prior CD or FCD release
+
Notification
+
The TC chair sends the release link to the TC for Pre-DP review.
+
+ +

Leaving this status:

+ +

When the Pre-DP review is complete:

+
    +
  1. DG chair: Notifies the TC chair the document is ready for DP Ballot.
    2. +
  2. TC chair: Requests/starts DP Ballot from SMPTE HO.
    3. +
  3. The document is now in .
    4. +
+
+ +
+

DP-ballot — DP ballot period

+
+
Description
+
The TC conducts the DP ballot to determine whether the document advances to Draft Publication.
+
Metadata
+
pubState=pub, pubStage=FCD, pubConfidential=yes
+
Branch
+
Status lives on main.
+
Latest release
+
YYYYMMDD-fcd
+
Redline
+
release-rl.html versus the prior CD or FCD release
+
Notification
+
The TC chair sends the release link to the TC for the DP ballot.
+
+ +

Leaving this status:

+ +

When the DP ballot passes:

+
    +
  1. TC chair: Requests ST Audit package from DG.
    2. +
  2. Document editor: Branch YYYYMMDD-dp from main.
    3. +
  3. Document editor: On the new branch, set pubStage=DP. (pubState remains pub.)
    4. +
  4. Document editor: Open a Pull Request from the new branch to main.
    5. +
  5. DG chair: Reviews and approves the PR.
    6. +
  6. Merge the PR to main. The tooling auto-drafts a YYYYMMDD-dp release.
    7. +
  7. Publish the auto-drafted release per .
    8. +
  8. The document is now in .
    9. +
+ +

If the DP ballot does not pass:

+
    +
  1. Document editor: Branch YYYYMMDD-cdn+1 from main.
    2. +
  2. Document editor: On the new branch, set pubState=draft and pubStage=CD.
    3. +
  3. Document editor: Open a Pull Request from the new branch to main. The PR is the work container for the next status; do not merge yet.
    4. +
  4. The document is now in — back to the DG as a CD. Resolution work happens as additional commits to this open PR; the PR is merged when leaving CD-draft.
    5. +
+
+ +
+

DP-pub — Draft Publication

+
+
Description
+
DP release awaiting ST audit. Covers FCD ballot passes (no comments), DP ballot passes, and Ready for ST audit at the same metadata.
+
Metadata
+
pubState=pub, pubStage=DP, pubConfidential=yes
+
Branch
+
Status lives on main.
+
Latest release
+
YYYYMMDD-dp
+
Redline
+
release-rl.html versus the prior FCD or CD release
+
Notification
+
The TC chair sends the release link to DoS for ST audit.
+
+ +

Leaving this status:

+ +

When the document is ready for ST audit:

+
    +
  1. DG chair: Notifies the TC chair the document is ready for ST Audit.
    2. +
  2. TC chair: Requests/starts ST Audit from SMPTE HO.
    3. +
  3. The document is now in .
    4. +
+
+ +
+

ST-audit — ST audit period

+
+
Description
+
The Standards Committee (ST) conducts the audit to verify the document is ready for publication.
+
Metadata
+
pubState=pub, pubStage=DP, pubConfidential=yes
+
Branch
+
Status lives on main.
+
Latest release
+
YYYYMMDD-dp
+
Redline
+
release-rl.html versus the prior FCD or CD release
+
Notification
+
None — audit is in progress at DoS.
+
+ +

Leaving this status:

+ +

When the ST audit completes:

+
    +
  1. Document editor: Branch YYYYMMDD-pub from main.
    2. +
  2. Document editor: On the new branch, set pubStage=PUB and pubState=draft.
    3. +
  3. Document editor: Open a Pull Request from the new branch to main. The PR is the work container for the next status; do not merge yet.
    4. +
  4. The document is now in . Any final preparation happens as additional commits to this open PR; the PR is merged when leaving PUB-draft.
    5. +
+ +

If the ST audit does not pass:

+ +

An ST audit failure typically indicates a process issue rather than a content defect. No dedicated fall-back path exists at present; the procedure below routes the document back to CD-draft for resolution as a temporary measure.

+ +
    +
  1. Document editor: Branch YYYYMMDD-cdn+1 from main.
    2. +
  2. Document editor: On the new branch, set pubState=draft and pubStage=CD.
    3. +
  3. Document editor: Open a Pull Request from the new branch to main. The PR is the work container for the next status; do not merge yet.
    4. +
  4. The document is now in — back to the DG as a CD. Resolution happens as additional commits to this open PR; the PR is merged when leaving CD-draft.
    5. +
+
+ +
+

PUB-draft — Awaiting publication

+
+
Description
+
ST audit is complete; the document is held awaiting final publication.
+
Metadata
+
pubState=draft, pubStage=PUB, pubConfidential=yes
+
Branch
+
The YYYYMMDD-pub branch used to enter this status persists; the leaving change is made on this same branch.
+
Latest release
+
The prior YYYYMMDD-dp release. No release is auto-drafted on entering this status.
+
Redline
+
None on entry; the next release will produce pub-rl.html versus the prior published edition.
+
Notification
+
None — internal hold.
+
+ +

Leaving this status:

+ +

When ready to publish:

+
    +
  1. SMPTE HO: Creates an issue in to request the publication package from @TC/DG chair.
    2. +
  2. Document editor: On the open PR, set pubState=pub and pubConfidential=no.
    3. +
  3. DG chair: Reviews and approves the PR.
    4. +
  4. TC chair: Reviews and approves the PR.
    5. +
  5. Merge the PR to main. The tooling auto-drafts a YYYYMMDD-pub release.
    6. +
  6. Publish the auto-drafted release per .
    7. +
  7. TC chair: Sends release package to SMPTE HO, as a comment to the issue created.
    8. +
  8. The document is now in .
    9. +
+
+ +
+

PUB-pub — Published

+
+
Description
+
The document is published. The final release artifact is delivered to SMPTE HO for inclusion in . This is a terminal status for the current edition.
+
Metadata
+
pubState=pub, pubStage=PUB, pubConfidential=no
+
Branch
+
Status lives on main. Terminal — no further outgoing branch is created.
+
Latest release
+
YYYYMMDD-pub
+
Redline
+
pub-rl.html versus the prior published edition
+
Notification
+
The TC chair sends the release link to SMPTE HO for publication in . Automation for this step is planned for a future date.
+
+ +

Leaving this status:

+ +

None — this is a terminal status. A subsequent revision begins a new lifecycle from , working from this YYYYMMDD-pub release as the baseline.

+
+
- \ No newline at end of file + diff --git a/package-lock.json b/package-lock.json index d5e785e..7ea5362 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "smpte-html-pub-tooling", - "version": "2.0.1", + "version": "2.1.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "smpte-html-pub-tooling", - "version": "2.0.1", + "version": "2.1.0", "dependencies": { "@aws-sdk/client-iam": "^3.978.0", "@aws-sdk/client-s3": "^3.978.0",