Skip to content

Commit 52b6e7d

Browse files
AztecBotAztecBot
authored
chore(docs): update Netlify build configuration to use custom ignore script for docs changes (#19032)
## Summary Adds conditional build logic to Netlify deployments for both `docs/` and `barretenberg/docs/` sites. This prevents unnecessary doc preview builds on PRs that don't contain documentation changes, reducing CI noise and build costs. ## Problem Previously, every PR triggered docs preview builds regardless of whether documentation was changed. This caused: - Unnecessary preview deployments on non-docs PRs - Wasted build minutes - Clutter in PR checks Additionally, the previous ignore command (`git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF`) had a critical bug: when `CACHED_COMMIT_REF` is unset (which happens on new branches), the command becomes `git diff --quiet HEAD`, comparing the commit against the working directory instead of another commit. In a clean clone, this returns exit code 0 (no changes), incorrectly skipping builds that should run. ## Solution Implements a hybrid approach with custom ignore scripts that handle both production and preview deployments correctly: ### Production Deploys (`next` branch) - Uses `CACHED_COMMIT_REF` to compare against the last successfully deployed commit - Ensures nightly docs releases and other docs changes trigger builds - Falls back to building if `CACHED_COMMIT_REF` is unset (first deploy or cache reset) ### PR Preview Deploys (other branches) - Uses `git merge-base` to compare the PR against where it diverged from `next` - Only builds if the PR introduces docs-related changes - Works correctly even on first commit of new branches (no `CACHED_COMMIT_REF` dependency) ## What Triggers a Build ### For `docs/` site: - Changes in `docs/` directory - Changes in `noir-projects/aztec-nr/` (source for autogenerated API docs) - Changes in files referenced by `#include_code` macros ### For `barretenberg/docs/` site: - Changes in `barretenberg/docs/` directory - Changes in `barretenberg/cpp/src/barretenberg/` (Doxygen API source) - Changes in `barretenberg/cpp/docs/` (Doxygen config) - Changes in files referenced by `#include_code` macros ## Behavior Matrix | Scenario | Branch | Result | |----------|--------|--------| | PR with docs changes | feature-branch | **Build preview** | | PR without docs changes | feature-branch | **Skip** (no preview clutter) | | Push with docs changes | next | **Build production** | | Push without docs changes | next | **Skip** | | First deploy (no cached ref) | next | **Build** (safe fallback) | ## Files Changed - `docs/netlify.toml` - Updated to use custom ignore script - `docs/scripts/netlify-ignore-build.sh` - New ignore script for main docs - `barretenberg/docs/netlify.toml` - Updated to use custom ignore script - `barretenberg/docs/scripts/netlify-ignore-build.sh` - New ignore script for BB docs
2 parents 3e8eb4d + 81c88ef commit 52b6e7d

File tree

4 files changed

+166
-4
lines changed

4 files changed

+166
-4
lines changed

‎barretenberg/docs/netlify.toml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[build]
2-
# Only build if changes are made in the docs directory
3-
ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF"
2+
# Only build if docs-related files changed (docs/ or #include_code references)
3+
ignore = "./scripts/netlify-ignore-build.sh"
44

55
# Redirect root to /docs
66
[[redirects]]

‎barretenberg/docs/scripts/netlify-ignore-build.sh‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
#!/usr/bin/env bash
2+
# Netlify ignore script: Skip builds if no docs-related files changed
3+
# Exit 0 = skip build, Exit 1 = proceed with build
4+
#
5+
# This script runs from the barretenberg/docs/ directory (Netlify base)
6+
#
7+
# Strategy:
8+
# - Production deploys (next branch): Compare against CACHED_COMMIT_REF (last deployed commit)
9+
# - PR previews (other branches): Compare against merge-base with next (changes introduced by PR)
10+
#
11+
# This ensures:
12+
# - Production builds when docs change on next (including nightly releases)
13+
# - PR previews only build when the PR has docs changes (no clutter on non-docs PRs)
14+
15+
set -euo pipefail
16+
17+
BASE_BRANCH="next"
18+
19+
# Determine the comparison reference based on deploy context
20+
if [ "${BRANCH:-}" = "$BASE_BRANCH" ]; then
21+
# Production deploy on the base branch - use CACHED_COMMIT_REF
22+
if [ -z "${CACHED_COMMIT_REF:-}" ]; then
23+
echo "Production deploy without cached commit reference - proceeding with build"
24+
exit 1
25+
fi
26+
COMPARE_REF="$CACHED_COMMIT_REF"
27+
echo "Production deploy: comparing $COMMIT_REF against last deployed commit $COMPARE_REF"
28+
else
29+
# PR preview or branch deploy - use merge-base to detect PR-specific changes
30+
# Fetch the base branch to ensure we have it available for merge-base comparison
31+
git fetch origin "$BASE_BRANCH" 2>/dev/null || true
32+
33+
COMPARE_REF=$(git merge-base "origin/$BASE_BRANCH" "$COMMIT_REF" 2>/dev/null || echo "")
34+
35+
if [ -z "$COMPARE_REF" ]; then
36+
echo "Could not determine merge base with $BASE_BRANCH - proceeding with build"
37+
exit 1
38+
fi
39+
echo "PR preview: comparing $COMMIT_REF against merge base $COMPARE_REF (from $BASE_BRANCH)"
40+
fi
41+
42+
# Check for ANY changes in the docs/ directory (current directory in Netlify context)
43+
if ! git diff --quiet "$COMPARE_REF" "$COMMIT_REF" -- .; then
44+
echo "Changes detected in barretenberg/docs/ directory - proceeding with build"
45+
exit 1
46+
fi
47+
48+
# Check for changes in barretenberg/cpp/src/barretenberg (Doxygen source for API docs)
49+
if ! git diff --quiet "$COMPARE_REF" "$COMMIT_REF" -- ../cpp/src/barretenberg; then
50+
echo "Changes detected in barretenberg/cpp/src/barretenberg - proceeding with build"
51+
exit 1
52+
fi
53+
54+
# Check for changes in barretenberg/cpp/docs (Doxygen config and additional source)
55+
if ! git diff --quiet "$COMPARE_REF" "$COMMIT_REF" -- ../cpp/docs; then
56+
echo "Changes detected in barretenberg/cpp/docs - proceeding with build"
57+
exit 1
58+
fi
59+
60+
# Extract all #include_code file references from markdown files
61+
# Pattern: #include_code identifier /path/to/file language
62+
# Paths are relative to repo root (may start with /) or relative to docs
63+
INCLUDE_CODE_PATHS=$(
64+
find . -type f \( -name "*.md" -o -name "*.mdx" \) 2>/dev/null | \
65+
xargs grep -h '^#include_code' 2>/dev/null | \
66+
awk '{ gsub("^/", "", $3); print $3 }' | \
67+
sort -u || true
68+
)
69+
70+
# Check each referenced external file for changes
71+
for path in $INCLUDE_CODE_PATHS; do
72+
if [ -n "$path" ]; then
73+
# Check if path exists relative to current dir or relative to repo root
74+
if [ -f "./$path" ]; then
75+
# Path is relative to docs/ - already covered by the docs/ check above
76+
continue
77+
fi
78+
# Path is relative to repo root
79+
if ! git diff --quiet "$COMPARE_REF" "$COMMIT_REF" -- "../../$path" 2>/dev/null; then
80+
echo "Changes detected in included file: $path - proceeding with build"
81+
exit 1
82+
fi
83+
fi
84+
done
85+
86+
echo "No docs-related changes detected - skipping build"
87+
exit 0

‎docs/netlify.toml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
# BUILD CONFIGURATION
33
# =============================================================================
44
[build]
5-
# Only build if changes are made in the docs directory
6-
ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF"
5+
# Only build if docs-related files changed (docs/, aztec-nr/, or #include_code references)
6+
ignore = "./scripts/netlify-ignore-build.sh"
77
command = "yarn build"
88
functions = "netlify/functions"
99

‎docs/scripts/netlify-ignore-build.sh‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
#!/usr/bin/env bash
2+
# Netlify ignore script: Skip builds if no docs-related files changed
3+
# Exit 0 = skip build, Exit 1 = proceed with build
4+
#
5+
# This script runs from the docs/ directory (Netlify base)
6+
#
7+
# Strategy:
8+
# - Production deploys (next branch): Compare against CACHED_COMMIT_REF (last deployed commit)
9+
# - PR previews (other branches): Compare against merge-base with next (changes introduced by PR)
10+
#
11+
# This ensures:
12+
# - Production builds when docs change on next (including nightly releases)
13+
# - PR previews only build when the PR has docs changes (no clutter on non-docs PRs)
14+
15+
set -euo pipefail
16+
17+
BASE_BRANCH="next"
18+
19+
# Determine the comparison reference based on deploy context
20+
if [ "${BRANCH:-}" = "$BASE_BRANCH" ]; then
21+
# Production deploy on the base branch - use CACHED_COMMIT_REF
22+
if [ -z "${CACHED_COMMIT_REF:-}" ]; then
23+
echo "Production deploy without cached commit reference - proceeding with build"
24+
exit 1
25+
fi
26+
COMPARE_REF="$CACHED_COMMIT_REF"
27+
echo "Production deploy: comparing $COMMIT_REF against last deployed commit $COMPARE_REF"
28+
else
29+
# PR preview or branch deploy - use merge-base to detect PR-specific changes
30+
# Fetch the base branch to ensure we have it available for merge-base comparison
31+
git fetch origin "$BASE_BRANCH" 2>/dev/null || true
32+
33+
COMPARE_REF=$(git merge-base "origin/$BASE_BRANCH" "$COMMIT_REF" 2>/dev/null || echo "")
34+
35+
if [ -z "$COMPARE_REF" ]; then
36+
echo "Could not determine merge base with $BASE_BRANCH - proceeding with build"
37+
exit 1
38+
fi
39+
echo "PR preview: comparing $COMMIT_REF against merge base $COMPARE_REF (from $BASE_BRANCH)"
40+
fi
41+
42+
# Check for ANY changes in the docs/ directory (current directory in Netlify context)
43+
if ! git diff --quiet "$COMPARE_REF" "$COMMIT_REF" -- .; then
44+
echo "Changes detected in docs/ directory - proceeding with build"
45+
exit 1
46+
fi
47+
48+
# Check for changes in noir-projects/aztec-nr (source for autogenerated aztec-nr docs)
49+
if ! git diff --quiet "$COMPARE_REF" "$COMMIT_REF" -- ../noir-projects/aztec-nr; then
50+
echo "Changes detected in noir-projects/aztec-nr - proceeding with build"
51+
exit 1
52+
fi
53+
54+
# Extract all #include_code file references from markdown files
55+
# Pattern: #include_code identifier /path/to/file language
56+
# Paths are relative to repo root
57+
INCLUDE_CODE_PATHS=$(
58+
find . -type f \( -name "*.md" -o -name "*.mdx" \) 2>/dev/null | \
59+
xargs grep -h '^#include_code' 2>/dev/null | \
60+
awk '{ gsub("^/", "", $3); print $3 }' | \
61+
sort -u || true
62+
)
63+
64+
# Check each referenced external file for changes
65+
for path in $INCLUDE_CODE_PATHS; do
66+
if [ -n "$path" ]; then
67+
if ! git diff --quiet "$COMPARE_REF" "$COMMIT_REF" -- "../$path" 2>/dev/null; then
68+
echo "Changes detected in included file: $path - proceeding with build"
69+
exit 1
70+
fi
71+
fi
72+
done
73+
74+
echo "No docs-related changes detected - skipping build"
75+
exit 0

0 commit comments

Comments
 (0)