Automate release drafting and redline base from git tags (new redlines)

.smpte-build.json

@@ -1,3 +1,3 @@
 {
-  "latestEditionTag": "20260319-pub"
+  "latestEditionTag": null
 }

doc/main.html

@@ -9,8 +9,8 @@
   <meta itemprop="pubType" content="AG">
   <meta itemprop="pubNumber" content="26">
   <!-- <meta itemprop="pubPart" content="XX"> -->
-  <meta itemprop="pubState" content="pub">
-  <!-- meta itemprop="pubStage" content="WD"> -->
+  <meta itemprop="pubState" content="draft">
+  <meta itemprop="pubStage" content="PUB">
   <meta itemprop="pubConfidential" content="no">
   <!--< meta itemprop="pubTC" content="XX"> -->
   <meta itemprop="pubSuiteTitle" content="HTML Pub">
@@ -1639,23 +1639,25 @@ <h4>Building</h4>
 
       <p>The S3 upload step can be skipped by providing the <code>validate</code> argument to the build script.</p>
 
-      <p>The build process can be configured using the <code>.smpte-build.json</code> file which is contains a JSON object that
-      conforms to the JSON schema at <a href="#figure-build-configuration-schema"></a>.</p>
+      <p>The build process MAY be configured using an optional <code>.smpte-build.json</code> file containing a JSON object that
+      conforms to the JSON schema at <a href="#figure-build-configuration-schema"></a>. When the file is absent, the build derives
+      its configuration from the document metadata and the repository's git tags.</p>
 
       <figure id="figure-build-configuration-schema">
         <pre data-include="../json/schema/build-configuration.json"></pre>
-        <figcaption>Schema for the build configuration file <code>.smpte-build.json</code>.</figcaption>
+        <figcaption>Schema for the optional build configuration file <code>.smpte-build.json</code>.</figcaption>
       </figure>
 
-      <p>If present or not equal to <code>null</code>, the <code>latestEditionTag</code> property contains the Git tag or commit
-      that is used when generating a redline against the latest published edition of the document.</p>
+      <p>If present and not equal to <code>null</code>, the <code>latestEditionTag</code> property overrides the auto-selected
+      redline base with the specified Git tag or commit. When absent or <code>null</code>, the redline base is auto-selected as
+      described in <a href="#sec-document-github-releases"></a>.</p>
 
       <div class="example">
   <pre data-include="../.smpte-build.json"></pre>
       </div>
 
       <p>
-        For further explanation of determining the value of <code>latestEditionTag</code>, see <a href="#sec-document-github-releases"></a>
+        For further explanation of how the redline base is determined, see <a href="#sec-document-github-releases"></a>.
       </p>
     </section>
 
@@ -2834,28 +2836,32 @@ <h3>Mapping <code>meta</code> tags to Document Status</h3>
     <section id="sec-document-github-releases">
       <h3>GitHub Releases</h3>
       <p>
-        Whenever the state of the document changes to <code>&lt;meta itemprop="pubState" content="pub" /&gt;</code> on the <code>main</code> branch, then a release shall be created in the GitHub repo. 
+        Whenever the state of the document changes to <code>&lt;meta itemprop="pubState" content="pub" /&gt;</code> on the <code>main</code> branch, the tooling automatically creates a <em>draft</em> release in the GitHub repo. An authorized editor reviews and publishes the draft to finalize the release and trigger production of the associated artifacts.
       </p>
       <p>
-        Both the GitHub release and git tag shall be named <code>YYYYMMDD "-" pubStage</code>. The <code>YYYYMMDD</code> should directly represent the value used in <code>pubDateTime</code> as defined in <a href="#sec-pubDateTime"></a>. 
+        Both the GitHub release and the git tag shall be named <code>YYYYMMDD "-" pubStage</code>, where <code>YYYYMMDD</code> directly represents the value of <code>pubDateTime</code> (as defined in <a href="#sec-pubDateTime"></a>) and the <code>pubStage</code> suffix is the value of the <code>pubStage</code> meta in lowercase.
       </p>
       <p class="example">
         <code>20230615-fcd</code> or <code>20230925-pub</code>
       </p>
       <p>
-        The <code>latestEditionTag</code> property in the <code>.smpte-build.json</code> file shall always be equal to the name of the most recent git tag. This will trigger the tooling to create a link for <code>Redline to most recent edition</code> during any PRs and merges to the <code>main</code> branch. 
+        The tooling determines the redline base automatically. When <code>pubStage</code> is <code>PUB</code>, the redline is generated against the most recent prior <code>-pub</code> tag (the previous edition); for any other <code>pubStage</code>, the redline is generated against the most recent prior dated tag of any stage (iterative draft-to-draft). The <code>Redline to most recent edition</code> link is generated for every PR and merge to <code>main</code> without manual configuration. If no prior matching tag exists, the redline is omitted. A <code>latestEditionTag</code> value MAY be set in <code>.smpte-build.json</code> to override the auto-selected base &mdash; for example, when rebuilding an archived edition or pinning to a specific historical release.
       </p>
       <p>
-        The tooling will automatically generate zip file packages within the release details page, to be used for both :</p>
-        <ul>
-          <li>TC review/balloting (named as per <a href="#bib-smpte-ag-02"></a>)</li>
-          <li>(and) SMPTE Document Library publishing (named by the tag)</li>
-        </ul>
-
-      <p class="example">See <a>https://github.com/SMPTE/st428-24-private/releases/tag/20241101-dp</a>, where <a>https://github.com/SMPTE/st428-24-private/releases/download/20241101-dp/27c-st-428-24-dp-2024-12-06-pub.zip</a> (ballot zip), and <a>https://github.com/SMPTE/st428-24-private/releases/download/20241101-dp/20241101-dp.zip</a> (publish zip) are available. </p>
-
+        For workflow events that share both <code>pubDateTime</code> and <code>pubStage</code> with the most recent release but represent a distinct release moment (e.g., entering the PCD period from a Pre-FCD review on the same day), the merge commit message shall include the token <code>[force-release]</code>. The tooling appends a numeric suffix (<code>-2</code>, <code>-3</code>, &hellip;) to the tag to disambiguate.
+      </p>
+      <p>
+        Publishing the draft release triggers the tooling to automatically generate zip file packages and attach them to the release details page, used for:
+      </p>
+      <ul>
+        <li>TC review/balloting (named as per <a href="#bib-smpte-ag-02"></a>)</li>
+        <li>SMPTE Document Library publishing (named by the tag)</li>
+      </ul>
+      <p class="example">
+        See <a>https://github.com/SMPTE/st428-24-private/releases/tag/20241101-dp</a>, where <a>https://github.com/SMPTE/st428-24-private/releases/download/20241101-dp/27c-st-428-24-dp-2024-12-06-pub.zip</a> (ballot zip) and <a>https://github.com/SMPTE/st428-24-private/releases/download/20241101-dp/20241101-dp.zip</a> (publish zip) are available.
+      </p>
       <p>
-        See <a href="#sec-sample-workflow"></a> for a sample workflow utilizing releases. 
+        See <a href="#sec-sample-workflow"></a> for a sample workflow utilizing releases.
       </p>
 
     </section>

json/schema/build-configuration.json

@@ -4,7 +4,7 @@
   "type": "object",
   "properties": {
     "latestEditionTag": {
-      "description": "Git commit or tag used when generating redlines against the latest edition of the document",
+      "description": "Optional override for the redline base. When set, the build uses this git commit or tag when generating redlines against the latest edition. When unset or null, the build auto-derives the redline base from the most recent matching git tag (most recent prior `-pub` tag when the document's pubStage is PUB; otherwise the most recent prior dated tag of any stage).",
       "type": [ "string", "null" ]
     }
   }

scripts/build.mjs

@@ -671,13 +671,51 @@ class BuildConfig {
     try {
       config = JSON.parse(fs.readFileSync(path.join(docDirPath, ".smpte-build.json")));
     } catch {
-      console.log("Could not read the publication config file.");
+      /* file is optional; auto-derivation is used when it is absent */
     }
 
-    this.lastEdRef = config.latestEditionTag || null;
+    this.latestEditionTag = config.latestEditionTag || null;
   }
 }
 
+const DATED_TAG_RE = /^\d{8}-(pub|fcd|cd|wd|dp)$/;
+
+function deriveLastEdRef(pubStage, override) {
+  if (override !== null && override !== undefined && override !== "") {
+    return override;
+  }
+
+  const editionOnly = pubStage === "PUB";
+  const globs = editionOnly ? ["*-pub"] : ["*-pub", "*-fcd", "*-cd", "*-wd", "*-dp"];
+
+  let allTags;
+  try {
+    allTags = child_process.execSync(`git tag -l ${globs.map(g => `'${g}'`).join(" ")} --sort=-version:refname`)
+      .toString()
+      .split("\n")
+      .map(t => t.trim())
+      .filter(t => DATED_TAG_RE.test(t));
+  } catch {
+    return null;
+  }
+
+  let headTags;
+  try {
+    headTags = new Set(
+      child_process.execSync("git tag --points-at HEAD")
+        .toString()
+        .split("\n")
+        .map(t => t.trim())
+        .filter(Boolean)
+    );
+  } catch {
+    headTags = new Set();
+  }
+
+  const candidate = allTags.find(t => !headTags.has(t));
+  return candidate || null;
+}
+
 async function main() {
   /* retrieve build phase */
 
@@ -802,7 +840,9 @@ async function main() {
 
   /* render document */
 
-  Object.assign(generatedFiles, await build(buildPaths, baseRef, config.lastEdRef, docMetadata));
+  const lastEdRef = deriveLastEdRef(docMetadata.pubStage, config.latestEditionTag);
+
+  Object.assign(generatedFiles, await build(buildPaths, baseRef, lastEdRef, docMetadata));
 
   /* validate rendered document */
 

scripts/derive-release-tag.mjs

@@ -0,0 +1,81 @@
+/* (c) Society of Motion Picture and Television Engineers
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */
+
+import * as fs from "fs";
+import process from "process";
+import { argv } from "process";
+
+const PUB_STAGES = new Set(["WD", "CD", "FCD", "DP", "PUB"]);
+
+function extractMeta(html, name) {
+  const re = new RegExp(`<meta[^>]*itemprop=["']${name}["'][^>]*content=["']([^"']*)["']`, "i");
+  const m = html.match(re);
+  if (m) return m[1];
+  const reSwapped = new RegExp(`<meta[^>]*content=["']([^"']*)["'][^>]*itemprop=["']${name}["']`, "i");
+  const m2 = html.match(reSwapped);
+  return m2 ? m2[1] : null;
+}
+
+function emit(tag) {
+  if (process.env.GITHUB_OUTPUT) {
+    fs.appendFileSync(process.env.GITHUB_OUTPUT, `tag=${tag}\n`);
+  }
+  process.stdout.write(`tag=${tag}\n`);
+}
+
+const docPath = argv[2] || "doc/main.html";
+
+if (!fs.existsSync(docPath)) {
+  console.error(`Document not found: ${docPath}`);
+  process.exit(1);
+}
+
+const html = fs.readFileSync(docPath, "utf8");
+const headEnd = html.search(/<\/head>/i);
+const head = headEnd >= 0 ? html.slice(0, headEnd) : html;
+
+const pubState = extractMeta(head, "pubState");
+const pubDateTime = extractMeta(head, "pubDateTime");
+const pubStage = extractMeta(head, "pubStage");
+
+if (pubState !== "pub") {
+  emit("");
+  process.exit(0);
+}
+
+if (pubDateTime === null || !/^\d{4}-\d{2}-\d{2}$/.test(pubDateTime)) {
+  console.error(`pubDateTime must be a full YYYY-MM-DD date to form a release tag. Got: ${pubDateTime}`);
+  process.exit(1);
+}
+
+if (pubStage === null || !PUB_STAGES.has(pubStage)) {
+  console.error(`pubStage must be one of ${[...PUB_STAGES].join(", ")} to form a release tag. Got: ${pubStage}`);
+  process.exit(1);
+}
+
+const tag = `${pubDateTime.replace(/-/g, "")}-${pubStage.toLowerCase()}`;
+emit(tag);

workflows/action.yml

@@ -47,6 +47,41 @@ runs:
         node ${GITHUB_ACTION_PATH}/../scripts/build.mjs deploy
         cat ./build/vars.txt > "$GITHUB_OUTPUT"
 
+    - name: Create draft release if pubState=pub on main
+      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      shell: bash
+      env:
+        GITHUB_TOKEN: ${{ inputs.GITHUB_TOKEN }}
+      run: |
+        TAG=$(node ${GITHUB_ACTION_PATH}/../scripts/derive-release-tag.mjs | grep '^tag=' | head -1 | cut -d= -f2)
+        if [[ -z "$TAG" ]]; then
+          echo "pubState != pub or metadata incomplete; skipping draft release."
+          exit 0
+        fi
+        FORCE=""
+        if [[ "${{ github.event.head_commit.message }}" == *"[force-release]"* ]]; then
+          FORCE="1"
+        fi
+        FINAL_TAG="$TAG"
+        if git rev-parse "refs/tags/${TAG}" >/dev/null 2>&1; then
+          if [[ -z "$FORCE" ]]; then
+            echo "Tag ${TAG} already exists; no-op."
+            exit 0
+          fi
+          FINAL_TAG=""
+          for i in $(seq 2 99); do
+            if ! git rev-parse "refs/tags/${TAG}-${i}" >/dev/null 2>&1; then
+              FINAL_TAG="${TAG}-${i}"
+              break
+            fi
+          done
+          if [[ -z "$FINAL_TAG" ]]; then
+            echo "Could not resolve a free suffix for ${TAG} after 99 attempts." >&2
+            exit 1
+          fi
+        fi
+        gh release create "$FINAL_TAG" --draft --title "$FINAL_TAG" --target "$GITHUB_SHA" --generate-notes
+
     - name: Determine which pull request we are on
       uses: jwalton/gh-find-current-pr@v1
       if: github.event_name == 'pull_request'