|
| 1 | +# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. |
| 2 | +# SPDX-License-Identifier: Apache-2.0 |
| 3 | +# |
| 4 | +# Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | +# you may not use this file except in compliance with the License. |
| 6 | +# You may obtain a copy of the License at |
| 7 | +# |
| 8 | +# http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | +# |
| 10 | +# Unless required by applicable law or agreed to in writing, software |
| 11 | +# distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | +# See the License for the specific language governing permissions and |
| 14 | +# limitations under the License. |
| 15 | + |
| 16 | +# Restores frozen backward-version page trees into the working copy so the Fern |
| 17 | +# build sees every version train, even though only the nightly tree (top-level |
| 18 | +# docs/) is kept on main. Each archived version's pages/ tree lives on a separate |
| 19 | +# git ref (a long-lived archive branch by default, or a docs/v* tag for an |
| 20 | +# immutable snapshot) and is restored into docs/fern/versions/<vdir>/pages. |
| 21 | +# |
| 22 | +# Fern has no native cross-ref version sourcing: `fern generate --docs` reads the |
| 23 | +# single local working tree, so the archived pages must physically exist before |
| 24 | +# `fern check` / `fern generate` runs. This action provides that materialization. |
| 25 | +# |
| 26 | +# The archive ref is treated as an opaque git ref, so a branch and a tag flow |
| 27 | +# through the same code path -- only the registry value differs. |
| 28 | + |
| 29 | +name: Stitch archived Fern version pages |
| 30 | +description: Restore frozen pages/ trees from an archive branch or docs/v* tag into docs/fern/versions/<vdir>/pages. |
| 31 | + |
| 32 | +inputs: |
| 33 | + archived-versions: |
| 34 | + description: >- |
| 35 | + Newline-separated list of "<version-dir>=<git-ref>" pairs. <version-dir> is |
| 36 | + the directory under docs/fern/versions/ (e.g. "v0.4"); <git-ref> is the |
| 37 | + branch or tag holding that version's frozen pages (e.g. "docs-archive" or |
| 38 | + "docs/v0.4.0"). The `latest` train is an alias of an existing pages tree and |
| 39 | + needs no entry. |
| 40 | + required: true |
| 41 | + |
| 42 | +runs: |
| 43 | + using: composite |
| 44 | + steps: |
| 45 | + - name: Restore archived version pages |
| 46 | + shell: bash |
| 47 | + env: |
| 48 | + ARCHIVED_VERSIONS: ${{ inputs.archived-versions }} |
| 49 | + run: | |
| 50 | + set -euo pipefail |
| 51 | + while IFS='=' read -r vdir ref; do |
| 52 | + vdir="$(echo "${vdir}" | xargs)" # trim surrounding whitespace |
| 53 | + ref="$(echo "${ref}" | xargs)" |
| 54 | + [ -z "${vdir}" ] && continue |
| 55 | + subtree="docs/fern/versions/${vdir}/pages" |
| 56 | + echo "::group::Stitch ${vdir} from ${ref}" |
| 57 | + # Shallow-fetch the ref. Works for a branch or a tag alike and does not |
| 58 | + # need a full-history (fetch-depth: 0) checkout. actions/checkout has |
| 59 | + # already configured the authenticated 'origin' remote, so fetching the |
| 60 | + # base repo's own ref needs no extra secret. |
| 61 | + git fetch --depth=1 origin "${ref}" --quiet |
| 62 | + # Hard-fail if the ref or the subtree is missing -- a silent miss would |
| 63 | + # otherwise drop the version from the published site (publish is a full |
| 64 | + # snapshot, not incremental). |
| 65 | + if [ -z "$(git ls-tree -r --name-only FETCH_HEAD -- "${subtree}")" ]; then |
| 66 | + echo "::error::archive ref '${ref}' does not contain '${subtree}'" |
| 67 | + exit 1 |
| 68 | + fi |
| 69 | + # Restore ONLY the frozen pages subtree from the ref. docs.yml and the |
| 70 | + # nav YAMLs always come from the live checkout, never the archive ref, |
| 71 | + # so editorial changes on the current branch always win and the frozen |
| 72 | + # prose can never drift into the wrong train. |
| 73 | + git restore --source=FETCH_HEAD --worktree --no-overlay -- "${subtree}" |
| 74 | + echo " restored $(git ls-tree -r --name-only FETCH_HEAD -- "${subtree}" | wc -l | xargs) files into ${subtree}" |
| 75 | + echo "::endgroup::" |
| 76 | + done <<< "${ARCHIVED_VERSIONS}" |
0 commit comments