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

.smpte-build.json

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

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

@@ -157,7 +157,7 @@ function mirrorDirExcludeTooling(srcDir, targetDir, relParentPath) {
 }
 
 
-async function build(buildPaths, baseRef, lastEdRef, docMetadata) {
+async function build(buildPaths, baseRef, lastEdRef, lastReleaseRef, docMetadata) {
 
   const generatedFiles = {};
 
@@ -197,19 +197,34 @@ async function build(buildPaths, baseRef, lastEdRef, docMetadata) {
 
   }
 
-  /* generate pub redline, if requested */
-
-  if (lastEdRef !== null) {
+  /* fetch tags once for both pub and release redlines */
 
+  if (lastEdRef !== null || lastReleaseRef !== null) {
     child_process.execSync(`git fetch --tags`);
+  }
+
+  /* generate redline against most recent published edition, if requested */
+
+  if (lastEdRef !== null) {
 
-    console.log(`Generating a redline against the latest edition tag: ${lastEdRef}.`);
+    console.log(`Generating a redline against the latest published edition tag: ${lastEdRef}.`);
 
     await generateRedline(buildPaths, lastEdRef, buildPaths.pubRedLineRefPath, buildPaths.pubRedlinePath);
     generatedFiles.pubRedline = buildPaths.pubRedlineName;
 
   }
 
+  /* generate redline against most recent release tag, if requested */
+
+  if (lastReleaseRef !== null) {
+
+    console.log(`Generating a redline against the latest release tag: ${lastReleaseRef}.`);
+
+    await generateRedline(buildPaths, lastReleaseRef, buildPaths.releaseRedLineRefPath, buildPaths.releaseRedlinePath);
+    generatedFiles.releaseRedline = buildPaths.releaseRedlineName;
+
+  }
+
   return generatedFiles;
 }
 
@@ -245,7 +260,10 @@ async function generatePubLinks(buildPaths, pubLinks) {
       linksDocContents += `[Redline to current draft](${pubLinks.baseRedline})\n`;
 
     if ("pubRedline" in pubLinks)
-      linksDocContents += `[Redline to most recent edition](${pubLinks.pubRedline})\n`;
+      linksDocContents += `[Redline to most recent published edition](${pubLinks.pubRedline})\n`;
+
+    if ("releaseRedline" in pubLinks)
+      linksDocContents += `[Redline to most recent release](${pubLinks.releaseRedline})\n`;
 
     if ("reviewZip" in pubLinks)
       linksDocContents += `[ZIP package](${pubLinks.reviewZip})\n`;
@@ -297,6 +315,10 @@ async function s3Upload(buildPaths, versionKey, generatedFiles) {
     pubLinks.pubRedline = `${deployPrefix}${s3PubKeyPrefix}${encodeURIComponent(generatedFiles.pubRedline)}`;
   }
 
+  if ("releaseRedline" in generatedFiles) {
+    pubLinks.releaseRedline = `${deployPrefix}${s3PubKeyPrefix}${encodeURIComponent(generatedFiles.releaseRedline)}`;
+  }
+
   if ("reviewZip" in generatedFiles) {
     pubLinks.reviewZip = `${deployPrefix}${s3PubKeyPrefix}${encodeURIComponent(generatedFiles.reviewZip)}`;
   }
@@ -334,6 +356,9 @@ async function makeReviewZip(buildPaths, generatedFiles, docMetadata) {
   if ("pubRedline" in generatedFiles)
     zip.addLocalFile(path.join(buildPaths.pubDirPath, generatedFiles.pubRedline));
 
+  if ("releaseRedline" in generatedFiles)
+    zip.addLocalFile(path.join(buildPaths.pubDirPath, generatedFiles.releaseRedline));
+
   /* create zip filename */
 
   const comps = [];
@@ -383,7 +408,11 @@ async function makePubArtifacts(buildPaths, generatedFiles, docMetadata) {
   }
 
   if ("pubRedline" in generatedFiles) {
-    htmlLinks += `<p><a href="${encodeURIComponent(generatedFiles.pubRedline)}">Redline to most recent edition</a></p>\n`;
+    htmlLinks += `<p><a href="${encodeURIComponent(generatedFiles.pubRedline)}">Redline to most recent published edition</a></p>\n`;
+  }
+
+  if ("releaseRedline" in generatedFiles) {
+    htmlLinks += `<p><a href="${encodeURIComponent(generatedFiles.releaseRedline)}">Redline to most recent release</a></p>\n`;
   }
 
   if (generatedFiles.reviewZip !== undefined) {
@@ -655,6 +684,10 @@ class BuildPaths {
     this.pubRedlinePath = path.join(this.pubDirPath, this.pubRedlineName);
     this.pubRedLineRefPath = path.join(this.buildDirPath, this.pubRedlineName);
 
+    this.releaseRedlineName = "release-rl.html";
+    this.releaseRedlinePath = path.join(this.pubDirPath, this.releaseRedlineName);
+    this.releaseRedLineRefPath = path.join(this.buildDirPath, this.releaseRedlineName);
+
     this.baseRedlineName = "base-rl.html";
     this.baseRedlinePath = path.join(this.pubDirPath, this.baseRedlineName);
     this.baseRedLineRefPath = path.join(this.buildDirPath, this.baseRedlineName);
@@ -671,13 +704,59 @@ 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)(-\d+)?$/;
+const PUB_TAG_RE = /^\d{8}-pub(-\d+)?$/;
+
+function getHeadTags() {
+  try {
+    return new Set(
+      child_process.execSync("git tag --points-at HEAD")
+        .toString()
+        .split("\n")
+        .map(t => t.trim())
+        .filter(Boolean)
+    );
+  } catch {
+    return new Set();
+  }
+}
+
+function pickLatestTag(globs, filterRe) {
+  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 => filterRe.test(t));
+  } catch {
+    return null;
+  }
+
+  const headTags = getHeadTags();
+  return allTags.find(t => !headTags.has(t)) || null;
+}
+
+function deriveLastEdRef(override) {
+  if (override !== null && override !== undefined && override !== "") {
+    return override;
+  }
+  return pickLatestTag(["*-pub*"], PUB_TAG_RE);
+}
+
+function deriveLastReleaseRef(pubStage) {
+  /* a -pub release only needs the redline to the prior published edition */
+  if (pubStage === "PUB") return null;
+  return pickLatestTag(["*-pub*", "*-fcd*", "*-cd*", "*-wd*", "*-dp*"], DATED_TAG_RE);
+}
+
 async function main() {
   /* retrieve build phase */
 
@@ -802,7 +881,10 @@ async function main() {
 
   /* render document */
 
-  Object.assign(generatedFiles, await build(buildPaths, baseRef, config.lastEdRef, docMetadata));
+  const lastEdRef = deriveLastEdRef(config.latestEditionTag);
+  const lastReleaseRef = deriveLastReleaseRef(docMetadata.pubStage);
+
+  Object.assign(generatedFiles, await build(buildPaths, baseRef, lastEdRef, lastReleaseRef, 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'