| 1 | --- |
| 2 | name: learn-pr-preview |
| 3 | description: Use only when the user explicitly asks to build, run, preview, inspect, or validate learn.netdata.cloud locally using the contents of a PR or documentation branch before merge. Do not trigger for ordinary docs edits unless the user asks for a local Learn preview. |
| 4 | --- |
| 5 | |
| 6 | # learn-pr-preview |
| 7 | |
| 8 | Build and inspect a local Learn site from a PR's documentation content without |
| 9 | dirtying the real Learn checkout. |
| 10 | |
| 11 | Always load `learn-site-structure` first. If the PR touches `metadata.yaml` or |
| 12 | generated integration pages, also load `integrations-lifecycle`. |
| 13 | |
| 14 | ## Rules |
| 15 | |
| 16 | - Trigger only on an explicit preview/build/inspect request. |
| 17 | - Do not run ingest directly in a dirty Learn worktree. |
| 18 | - Use an isolated preview directory under `/tmp` or the repo's gitignored |
| 19 | `.local/`. |
| 20 | - Record the Learn branch and commit used for the preview. |
| 21 | - Copy PR source content into an isolated source directory. Prefer committed |
| 22 | PR content; if validating uncommitted work, copy tracked modified files and |
| 23 | only intentional untracked docs files after checking `git status --short`. |
| 24 | - Save any preview server PID and kill only that PID when stopping it. |
| 25 | - Treat site-wide warnings as evidence, but separate pre-existing global Learn |
| 26 | warnings from PR-specific Network Flows or docs warnings. |
| 27 | |
| 28 | ## Workflow |
| 29 | |
| 30 | Set paths: |
| 31 | |
| 32 | ```bash |
| 33 | REPO_ROOT="$(git rev-parse --show-toplevel)" |
| 34 | PR_NUMBER="<pr-number>" |
| 35 | LEARN_REPO="${NETDATA_REPOS_DIR}/learn" |
| 36 | PREVIEW_ROOT="${TMPDIR:-/tmp}/netdata-learn-preview-pr-${PR_NUMBER}-$(date +%Y%m%d%H%M%S)" |
| 37 | SOURCE_COPY="${PREVIEW_ROOT}/netdata-source" |
| 38 | LEARN_COPY="${PREVIEW_ROOT}/learn" |
| 39 | ``` |
| 40 | |
| 41 | Create isolated copies: |
| 42 | |
| 43 | ```bash |
| 44 | mkdir -p "${SOURCE_COPY}" |
| 45 | git -C "${REPO_ROOT}" ls-files -co --exclude-standard -z \ |
| 46 | | rsync -a --from0 --files-from=- --ignore-missing-args "${REPO_ROOT}/" "${SOURCE_COPY}/" |
| 47 | |
| 48 | git clone --branch "$(git -C "${LEARN_REPO}" branch --show-current)" \ |
| 49 | --single-branch "${LEARN_REPO}" "${LEARN_COPY}" |
| 50 | git -C "${LEARN_COPY}" rev-parse HEAD |
| 51 | ``` |
| 52 | |
| 53 | Install ingest dependencies in the isolated preview: |
| 54 | |
| 55 | ```bash |
| 56 | python3 -m venv "${PREVIEW_ROOT}/venv" |
| 57 | "${PREVIEW_ROOT}/venv/bin/python" -m pip install --upgrade pip |
| 58 | "${PREVIEW_ROOT}/venv/bin/python" -m pip install \ |
| 59 | -r "${LEARN_COPY}/.learn_environment/ingest-requirements.txt" |
| 60 | ``` |
| 61 | |
| 62 | If the real Learn checkout has compatible `node_modules`, symlink it to avoid a |
| 63 | fresh install: |
| 64 | |
| 65 | ```bash |
| 66 | ln -s "${LEARN_REPO}/node_modules" "${LEARN_COPY}/node_modules" |
| 67 | ``` |
| 68 | |
| 69 | Run ingest with the PR source: |
| 70 | |
| 71 | ```bash |
| 72 | cd "${LEARN_COPY}" |
| 73 | "${PREVIEW_ROOT}/venv/bin/python" ingest/ingest.py \ |
| 74 | --local-repo "netdata:${SOURCE_COPY}" \ |
| 75 | --ignore-on-prem-repo \ |
| 76 | --use_plain_https \ |
| 77 | --fail-links-netdata |
| 78 | ``` |
| 79 | |
| 80 | Build with the Netlify-pinned runtime: |
| 81 | |
| 82 | ```bash |
| 83 | NODE_OPTIONS=--max_old_space_size=4096 \ |
| 84 | npx -y -p node@22.14.0 -p yarn@1.22.22 yarn build |
| 85 | ``` |
| 86 | |
| 87 | Serve the static build for inspection: |
| 88 | |
| 89 | ```bash |
| 90 | python3 -m http.server 3030 --bind 127.0.0.1 --directory "${LEARN_COPY}/build" |
| 91 | ``` |
| 92 | |
| 93 | Or run it in the background with a PID file: |
| 94 | |
| 95 | ```bash |
| 96 | python3 -m http.server 3030 --bind 127.0.0.1 --directory "${LEARN_COPY}/build" \ |
| 97 | >"${PREVIEW_ROOT}/http.log" 2>&1 & |
| 98 | echo "$!" > "${PREVIEW_ROOT}/http.pid" |
| 99 | ``` |
| 100 | |
| 101 | Inspect representative pages in a browser. For docs PRs, check: |
| 102 | |
| 103 | - the changed hand-authored pages; |
| 104 | - generated integration pages affected by `metadata.yaml`; |
| 105 | - the category index page; |
| 106 | - at least one page that previously failed ingest, MDX, or link checks. |
| 107 | |
| 108 | Report: |
| 109 | |
| 110 | - Learn branch and commit used; |
| 111 | - ingest command and exit status; |
| 112 | - build command and exit status; |
| 113 | - inspected URLs and HTTP/browser status; |
| 114 | - PR-specific warnings or failures; |
| 115 | - pre-existing global warnings separately. |