DataDesigner/.github/workflows/publish-fern-devnotes.yml

name: Publish Fern devnotes

on:
  push:
    branches: [main]
    paths:
      - "fern/assets/**"
      - "fern/components/Authors.tsx"
      - "fern/components/BlogCard.tsx"
      - "fern/components/MetricsTable.tsx"
      - "fern/components/TrajectoryViewer.tsx"
      - "fern/components/devnotes/**"
      - "fern/styles/authors.css"
      - "fern/styles/blog-card.css"
      - "fern/styles/metrics-table.css"
      - "fern/styles/trajectory-viewer.css"
      - "fern/versions/latest.yml"
      - "fern/versions/latest/pages/devnotes/**"
  workflow_dispatch:

permissions: {}

concurrency:
  group: fern-docs-website
  cancel-in-progress: false

env:
  FERN_PUBLISHED_BRANCH: docs-website

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: write
    env:
      FERN_TOKEN: ${{ secrets.DOCS_FERN_TOKEN }}
    steps:
      - name: Checkout workflow
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          path: workflow
          ref: ${{ github.event.repository.default_branch }}

      - name: Checkout source
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          path: source

      - name: Checkout published branch
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          fetch-depth: 0
          path: website

      - name: Prepare published branch checkout
        working-directory: website
        run: |
          if ! git ls-remote --exit-code --heads origin "$FERN_PUBLISHED_BRANCH" >/dev/null 2>&1; then
            echo "::error::$FERN_PUBLISHED_BRANCH does not exist. Publish a Fern release snapshot first."
            exit 1
          fi

          git fetch origin "$FERN_PUBLISHED_BRANCH" --depth=1
          git checkout -B "$FERN_PUBLISHED_BRANCH" FETCH_HEAD          

      - name: Patch Dev Notes into latest Fern docs
        env:
          SOURCE_REF: ${{ github.ref }}
          SOURCE_REPOSITORY: ${{ github.repository }}
          PUBLISHED_BRANCH: ${{ env.FERN_PUBLISHED_BRANCH }}
        run: |
          source_sha=$(git -C source rev-parse HEAD)
          python3 workflow/fern/scripts/fern-published-branch.py patch-devnotes \
            --source-root source \
            --published-root website \
            --metadata-source-repository "$SOURCE_REPOSITORY" \
            --metadata-source-ref "$SOURCE_REF" \
            --metadata-source-sha "$source_sha" \
            --metadata-published-branch "$PUBLISHED_BRANCH"          

      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
        with:
          version: "0.9.5"

      - name: Set up Python
        run: uv python install 3.13

      - name: Install docs dependencies
        working-directory: website
        run: uv sync --python 3.13 --all-packages --group docs --group notebooks

      - name: Reuse notebooks from last successful docs build
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          mkdir -p website/docs/notebooks

          download_notebooks() {
            workflow="$1"
            shift

            last_run_id=$(gh run list --repo "$GITHUB_REPOSITORY" --workflow "$workflow" --status success "$@" --limit 1 --json databaseId -q '.[0].databaseId // empty' 2>/dev/null || true)
            if [ -n "$last_run_id" ] && gh run download "$last_run_id" --repo "$GITHUB_REPOSITORY" --name notebooks --dir website/docs/notebooks; then
              echo "::notice::Downloaded notebooks from $workflow run $last_run_id"
              exit 0
            fi
          }

          for workflow in build-fern-docs.yml build-docs.yml; do
            download_notebooks "$workflow" --event release
          done

          for workflow in build-fern-docs.yml build-docs.yml; do
            download_notebooks "$workflow" --event workflow_dispatch --branch main
          done

          echo "::error::No successful docs build run with notebook artifacts found."
          exit 1          

      - name: Check Fern docs
        working-directory: website
        run: make check-fern-docs

      - name: Commit published branch
        env:
          SOURCE_REF: ${{ github.ref }}
          SOURCE_REPOSITORY: ${{ github.repository }}
        working-directory: website
        run: |
          if [ -z "$(git status --porcelain)" ]; then
            echo "::notice::Fern Dev Notes are already up to date."
            exit 0
          fi

          source_sha=$(git -C ../source rev-parse HEAD)
          previous_published_sha=$(git rev-parse HEAD)
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add -A
          git commit \
            -m "docs: patch Fern devnotes into latest" \
            -m "Source: $SOURCE_REPOSITORY@$SOURCE_REF ($source_sha)" \
            -m "Previous docs-website head: $previous_published_sha"
          git push origin HEAD:"$FERN_PUBLISHED_BRANCH"          

      - name: Publish Fern docs
        working-directory: website
        run: |
          if [ -z "$FERN_TOKEN" ]; then
            echo "::error::DOCS_FERN_TOKEN secret is required to publish Fern docs."
            exit 1
          fi

          cd fern
          fern_version=$(jq -r .version fern.config.json)
          if [[ ! "$fern_version" =~ ^[0-9]+[.][0-9]+[.][0-9]+([-.][0-9A-Za-z]+)*$ ]]; then
            echo "::error::Invalid Fern version in fern.config.json: $fern_version"
            exit 1
          fi

          npx -y "fern-api@$fern_version" generate --docs --no-prompt