[#26] Publish the last release of each previous major line as an older version

[vharseko]

Fixes #26

Publishes the last release of each previous major line as an older version; master stays the default version, so no URL changes.

Product	master (unchanged URLs)	Older version
OpenAM	/openam/…, shown as 16.x	/openam/15.2/…, 15.2.2 (tag OpenAM-15.2.2)
OpenDJ	/opendj/…, 5.x	/opendj/4.10/…, 4.10.2
OpenIDM	/openidm/…, 7.x	/openidm/6.3/…, 6.3.0
OpenIG	/openig/…, 6.x	/openig/5.3/…, 5.3.2

The version menus of the default UI (component list and the per-page version menu) show the older versions as soon as a component has more than one.

Why an extension (lib/versions-from-tags.js)

Listing the tags as content sources in the playbook is not enough:

1. the antora.yml of every tag declares version: ~, and Antora gives the version in antora.yml precedence over the version of the content source, so a tag would be merged into the unversioned component version built from master;
2. Antora reads every file under the start path of a git tree, and at a tag that includes the API docs of that time (18,672 files for OpenAM-15.2.2, against 330 pages): the build took 4m14s instead of 43s.

The extension replaces aggregateContent: the branch sources are aggregated as before; for each tag source it extracts only <product>/antora.yml and <product>/modules with git archive into a temporary repository under build/antora-tags/<tag> (a fixed path, so that the errors Antora logs for tag content can be listed in the baseline of #28), aggregates it separately and sets the version from the tag name (OpenAM-15.2.2 → version 15.2, display 15.2.2). The build now takes about 1m16s locally. If the tag is missing — as in the shallow actions/checkout of CI — the extension fetches it from origin (with --depth=1 in a shallow repository), so no workflow change is needed. If the fetch fails (e.g. a fork created before the tags were pushed, or no network), the build fails with the git fetch command that gets the tag from the upstream, followed by git's own error. The temporary commit runs with core.hooksPath=/dev/null, so global git hooks of a developer cannot abort the build.

Other changes

• <product>/antora.yml: display_version of master (16.x, 5.x, 7.x, 6.x).
• lib/add-pdf-link.js: the "Download PDF" link only on the latest version — the wiki PDFs are built from the current sources.
• lib/add-pdf-link.js, <product>/antora.yml: CDDL header with Copyright 2024-2026 3A Systems, LLC. — these files had no copyright line; the playbook got the same line in [#24] SEO: declare the sitemap in robots.txt, add description and OpenGraph tags #29.
• Tag sources have edit_url: false: no "Edit this Page" on older versions.
• docsearch/config.json: older versions (/<product>/<major>.<minor>/) added to stop_urls, so search does not mix them with the current docs.

Verification

Local builds:

• the 285 master pages differ from the current build only by the older versions added to the version menus; the start page still links to master;
• the canonical URL of an older page points to the same page in master (e.g. …/openam/admin-guide/); no PDF or edit link on older pages;
• CI scenario: a --depth 1 clone without tags — the extension fetched the 4 tags and the build succeeded;
• rebased onto master with [#21] Fix broken JEE agent PDF link and malformed header markup #27 and [#24] SEO: declare the sitemap in robots.txt, add description and OpenGraph tags #29 merged: the only conflict, the copyright line of antora-playbook.yml, resolved to master; merges with [#25] CI: build pull requests and make the site build reproducible #28 without conflicts;
• a --depth 1 --no-tags clone whose origin is unreachable: the build fails with cannot fetch tag OpenDJ-4.10.2 from the origin of …; if the tag is missing there, run git fetch …, then git's Couldn't connect to server;
• the OpenIG-5.3.2 copy of the known sec-release-levels.adoc error is logged as build/antora-tags/OpenIG-5.3.2/openig/modules/ROOT/partials/sec-release-levels.adoc with refname OpenIG-5.3.2, the same on every run;
• site size with API docs: 877 MB (GitHub Pages limit: 1 GB);
• lychee --offline: 106 broken links instead of 45. The new ones are the same legacy ForgeRock-era links inside the frozen tags, plus 8 links from openam/15.2 pages to openam/15.2/apidocs — the API docs are published for the current version only.

Merge order with #28

#28 adds a gate that fails a pull request on an Antora error or a broken link missing from .github/build-baseline. This PR adds one Antora error (the OpenIG-5.3.2 copy above) and the new broken links of the older versions. Whichever of the two lands second runs .github/build-baseline/check.sh --update on its build and commits both lists.

Not in this PR

• When a new major line is released (e.g. OpenAM 17), the tag in the playbook and display_version are updated by hand.
• The stray tag ${TAG_NAME} (0abcd92e4f) mentioned in Publish versioned docs from existing release tags #26 is not deleted yet; deleting a tag on origin is done separately.

[maximthomas]

praise: The extension publishes the tags without dragging their API docs or their version: ~ into the build.

• extractTag archives only ${startPath}/antora.yml and ${startPath}/modules (lib/versions-from-tags.js:84), so the 18,672 API-doc files of OpenAM-15.2.2 never reach the content catalogue.
• The version comes from the tag name (TAG_RX, lib/versions-from-tags.js:38, :58-59), so a tag cannot merge into the unversioned master component version.
• The missing-tag fetch adds --depth=1 only in a shallow repository (lib/versions-from-tags.js:80-81), and the temp repository is removed in a finally (:64-66).

---

question (non-blocking): Is #28's baseline gate meant to land as written? It cannot key errors from the random temp path the tag content is read from.

lib/versions-from-tags.js:48, :56, :65, :89

fs.mkdtempSync(os.tmpdir()/antora-tags-) gives each run a new directory, and Antora logs tag content with that absolute file.path, source.refname = the temp repo's default branch (main/master) and reftype branch; the directory is deleted before anyone reads the log. #28's check.sh keys errors as .file.path | ltrimstr("$root/"), which cannot strip a temp path: at this head the OpenIG-5.3.2 copy of sec-release-levels.adoc:20 ("level 0 sections can only be used when doctype is book") gets a new key on every run, so with both PRs merged the gate fails every build and --update cannot baseline it. If #28 lands first unchanged, this PR cannot pass the gate without the change below; otherwise it is a diagnostics fix.

      const tmpdir = ospath.join(playbook.dir, 'build', 'antora-tags')
      fs.rmSync(tmpdir, { recursive: true, force: true })
      fs.mkdirSync(tmpdir, { recursive: true })

Also, in extractTag, git(worktree, 'init', '-q', '-b', tag) (git ≥ 2.28) so refname names the tag; os is then unused.

---

suggestion (non-blocking): A tag missing both locally and on origin aborts the build with git's bare "couldn't find remote ref".

lib/versions-from-tags.js:76-82

In a clone whose origin is a fork created before the tags were pushed (maximthomas/doc.openidentityplatform.org has none: git ls-remote --tags), npm run build now stops at the first tag source with fatal: couldn't find remote ref refs/tags/OpenDJ-4.10.2; the same clone built at the base. CI is unaffected — its origin is the upstream, which has all four tags. Failing hard is right (a skip would publish without the older versions); the message can say what to do.

    try {
      git(repo, 'fetch', '-q', '--no-tags', ...(shallow ? ['--depth=1'] : []), 'origin', `+refs/tags/${tag}:refs/tags/${tag}`)
    } catch (err) {
      throw new Error(`tag ${tag} is neither in ${repo} nor on its origin; run ` +
        `git fetch https://github.com/OpenIdentityPlatform/doc.openidentityplatform.org tag ${tag}\n${err.stderr || err.message}`)
    }

---

issue (non-blocking): The temp-repo commit runs the developer's global git hooks.

lib/versions-from-tags.js:91-92

Only user.name, user.email and commit.gpgsign are overridden, so a global core.hooksPath (or init.templateDir) hook runs on git commit -m OpenAM-15.2.2. A conventional-commit commit-msg hook rejects that message, execFileSync throws and the local build aborts — reproduced with a global core.hooksPath and a commit-msg hook that exits 1. CI runners have no global hooks.

  git(worktree, '-c', 'user.name=antora', '-c', 'user.email=antora@localhost', '-c', 'commit.gpgsign=false',
    '-c', 'core.hooksPath=/dev/null', 'commit', '-q', '-m', tag)

---

issue (non-blocking): tar -x reads the archive from stdin without -f -.

lib/versions-from-tags.js:88

bsdtar's default archive is system-dependent (/dev/sa0 on FreeBSD; Windows tar.exe is bsdtar), and both tars honour $TAPE: with TAPE set, macOS bsdtar 3.5.3 exits 1 ("Failed to open …") and the build aborts. The runner's GNU tar works.

  execFileSync('tar', ['-x', '-f', '-', '-C', worktree], { input: archive })

[vharseko]

@maximthomas all four points are taken in e76cba2; the branch is also rebased onto the current master (#27, #35), without conflicts.

question — the gate of #28 and the temp path: fixed here, as suggested. The tags are extracted into build/antora-tags/<tag> (cleared before the run, removed after it), and the temp repository is created with init -b <tag>; os is gone. In a full build the tag error is now logged as

file.path: <repo>/build/antora-tags/OpenIG-5.3.2/openig/modules/ROOT/partials/sec-release-levels.adoc
refname:   OpenIG-5.3.2

so check.sh keys it as build/antora-tags/OpenIG-5.3.2/…, the same on every run. Beyond the Antora error, the gate also sees the new broken links of the older versions (106 instead of 45, including the 8 links from openam/15.2 pages to openam/15.2/apidocs, which --exclude-path does not cover, since it filters the pages, not the link targets). Their keys are site paths and stable, so whichever of #28 and #31 lands second runs check.sh --update and commits both lists; this is now noted in the description.

suggestion — missing tag: the fetch is wrapped; the build still fails, now with tag <tag> is neither in <repo> nor on its origin; run git fetch https://github.com/OpenIdentityPlatform/doc.openidentityplatform.org tag <tag> followed by git's stderr.

issue — global hooks: the commit runs with -c core.hooksPath=/dev/null, which also covers hooks copied by init.templateDir. --no-verify would not do, as it leaves prepare-commit-msg active.

issue — tar without -f -: now tar -x -f - -C <dir>. Checked with TAPE=/nonexistent/tape on macOS: the old call fails with /nonexistent/tape: No such file or directory, the new one extracts.

[maximthomas]

praise: All four round-1 points are fixed where the defects were, and the remaining known gap is now stated.

• Tags go to a fixed build/antora-tags/<tag>, and the temp repo is created with init -q -b <tag> (lib/versions-from-tags.js:49, :100), so the baseline of #28 gets the same path and refname on every run.
• -c core.hooksPath=/dev/null on the temp commit (:104) and tar -x -f - (:98).
• The openam/15.2 → openam/15.2/apidocs links and the merge order with #28 are in the description.

---

suggestion (non-blocking): Every failure of the tag fetch is reported as "tag X is neither in nor on its origin".

lib/versions-from-tags.js:86-89

The catch around the fetch at :85 rethrows any error with that first line. actions/checkout@v4 in publish.yml is shallow and fetches no tags, so CI always takes this fetch. A transient network or GitHub failure (reproduced with origin set to an unreachable URL: git says "Couldn't connect to server") then opens with a false cause and suggests a fetch that fails the same way. Git's own error is on the next line, so nothing is lost; only the first line is wrong.

    } catch (err) {
      // e.g. a fork created before the tag was pushed, or no network
      throw new Error(`cannot fetch tag ${tag} from the origin of ${repo}; if the tag is missing there, run ` +
        `git fetch https://github.com/OpenIdentityPlatform/doc.openidentityplatform.org tag ${tag}\n${err.stderr || err.message}`)
    }

---

nitpick (non-blocking): The new CDDL headers say "Portions Copyright 2026 3A Systems, LLC." in files that had no earlier copyright holder.

antora-playbook.yml:13, lib/add-pdf-link.js:14, opendj/antora.yml:13, openidm/antora.yml:13, openig/antora.yml:13

None of the five has a copyright line on master (git show b9afee40cc:<file> | grep -i copyright is empty), so "Portions" implies a holder that does not exist. This is the wording already corrected on antora-playbook.yml in the #29 review. The new lib/versions-from-tags.js:14 already has the right form.

# Copyright 2026 3A Systems, LLC.

[vharseko]

@maximthomas both points are taken in 01b0766; the branch is rebased onto the current master (#29), whose only conflict was the copyright line of antora-playbook.yml, resolved to master's Copyright 2024-2026 3A Systems, LLC.

suggestion — the fetch error: the message no longer names a cause: cannot fetch tag <tag> from the origin of <repo>; if the tag is missing there, run git fetch https://github.com/OpenIdentityPlatform/doc.openidentityplatform.org tag <tag>, followed by git's stderr. Checked with a --depth 1 --no-tags clone whose origin is https://127.0.0.1:9/…: the build fails with that line and then fatal: unable to access …: Couldn't connect to server.

nitpick — "Portions Copyright": changed to Copyright 2024-2026 3A Systems, LLC. in lib/add-pdf-link.js and the antora.yml of OpenDJ, OpenIDM and OpenIG, the same form and range as the playbook in #29: none of these files had a copyright line, and they date from 2024. I also changed openam/antora.yml, which got the same "Portions" line in #27 and which this PR edits anyway, so the four antora.yml stay alike. The playbook line comes from #29 after the rebase.

A full build at this head: the four older versions are published, the Antora errors are the four of master plus the OpenIG-5.3.2 copy at build/antora-tags/OpenIG-5.3.2/…, and build/antora-tags is removed afterwards.

[maximthomas]

praise: Both round-2 points are fixed where they were raised, and the copyright years follow each file's history.

• lib/versions-from-tags.js:88-89 no longer names a cause ("cannot fetch tag from the origin of ; if the tag is missing there, run …") and still ends with git's stderr. A network failure is no longer reported as a missing tag.
• Copyright 2024-2026 3A Systems, LLC. in lib/add-pdf-link.js:14 and the four */antora.yml:13 matches the year each file was created (2024-10-03 and 2024-09-20, git log --diff-filter=A). The new lib/versions-from-tags.js:14 says Copyright 2026.