fix: make Fern release publishing resilient#818
Conversation
|
Fern preview: https://nvidia-preview-pr-818.docs.buildwithfern.com/nemo/datadesigner
|
Greptile SummaryThis PR makes Fern docs publishing less dependent on live notebook execution. The main changes are:
|
| Filename | Overview |
|---|---|
| .github/workflows/build-fern-docs.yml | Decouples release snapshot preparation and Fern publishing from notebook execution, adds source-notebook fallback, restores rolling content, and verifies published URLs. |
| .github/workflows/build-notebooks.yml | Adds cache fingerprinting, artifact seeding, retry settings, and model health-check skipping, but now always passes USE_CACHE=1 to notebook execution. |
| .github/workflows/publish-fern-devnotes.yml | Pins setup-uv back to v8.1.0 for the Dev Notes publishing workflow. |
| docs/scripts/build_notebooks_cached.sh | Adds retry validation, retry cleanup, and runtime-context-aware notebook cache hashes. |
| packages/data-designer-engine/src/data_designer/engine/readiness.py | Adds an environment-variable gate to skip model health checks before generation. |
| packages/data-designer-engine/tests/engine/test_readiness.py | Adds coverage for skipping model health checks through the environment variable. |
| packages/data-designer/tests/docs/test_fern_published_branch.py | Extends published-branch tests for release metadata and versioned Dev Notes and Recipes preservation. |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[resolve release] --> B[prepare published release]
A --> C[build notebooks]
B --> D[publish Fern docs]
C --> D
C -->|success| E[download executed notebooks]
C -->|failure or cancelled| F[publish source notebook fallback]
E --> G[check and generate Fern docs]
F --> G
G --> H[verify latest and versioned URLs]
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
A[resolve release] --> B[prepare published release]
A --> C[build notebooks]
B --> D[publish Fern docs]
C --> D
C -->|success| E[download executed notebooks]
C -->|failure or cancelled| F[publish source notebook fallback]
E --> G[check and generate Fern docs]
F --> G
G --> H[verify latest and versioned URLs]
Prompt To Fix All With AI
Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 1
.github/workflows/build-notebooks.yml:97
**Cache Input Is Ignored**
Manual notebook runs with `use_cache: false` still execute `make convert-execute-notebooks USE_CACHE=1`. The cache restore and seed steps are skipped, but any `.notebook-cache` content left in the workspace can still be used by the script, so a run explicitly requesting fresh notebook execution can reuse cached notebooks instead.
```suggestion
make convert-execute-notebooks ${{ inputs.use_cache && 'USE_CACHE=1' || '' }}
```
Reviews (1): Last reviewed commit: "fix: restore working setup-uv action" | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| export DATA_DESIGNER_FLUX_2_PRO_CREATE_NUM_RECORDS=2 | ||
| fi | ||
| make convert-execute-notebooks ${{ inputs.use_cache && 'USE_CACHE=1' || '' }} | ||
| make convert-execute-notebooks USE_CACHE=1 |
There was a problem hiding this comment.
Manual notebook runs with use_cache: false still execute make convert-execute-notebooks USE_CACHE=1. The cache restore and seed steps are skipped, but any .notebook-cache content left in the workspace can still be used by the script, so a run explicitly requesting fresh notebook execution can reuse cached notebooks instead.
| make convert-execute-notebooks USE_CACHE=1 | |
| make convert-execute-notebooks ${{ inputs.use_cache && 'USE_CACHE=1' || '' }} |
Context Used: Do not suggest defensive coding patterns such as a... (source)
Prompt To Fix With AI
This is a comment left during a code review.
Path: .github/workflows/build-notebooks.yml
Line: 97
Comment:
**Cache Input Is Ignored**
Manual notebook runs with `use_cache: false` still execute `make convert-execute-notebooks USE_CACHE=1`. The cache restore and seed steps are skipped, but any `.notebook-cache` content left in the workspace can still be used by the script, so a run explicitly requesting fresh notebook execution can reuse cached notebooks instead.
```suggestion
make convert-execute-notebooks ${{ inputs.use_cache && 'USE_CACHE=1' || '' }}
```
**Context Used:** Do not suggest defensive coding patterns such as a... ([source](greptile.json))
How can I resolve this? If you propose a fix, please make it concise.
|
Thanks for putting this together, @andreatgretel — this untangles a genuinely gnarly release-workflow dependency chain, and the tests + PR writeup make the intent easy to follow. SummaryThis PR makes the Fern release path resilient to transient notebook-execution failures: it decouples release-snapshot preparation and publishing from the notebook job, adds provenance-aware artifact seeding, retries flaky notebook execution with backoff, restores rolling Dev Notes/Recipes into the release snapshot, verifies published URLs, and rolls FindingsWarnings — Worth addressing
Suggestions — Take it or leave it
What Looks Good
Structural Impact (graphify, 2.6s)Risk: LOW (localized change)
High-Connectivity Changes
Cross-Package Dependencies
Cross-package edges all flow interface → engine → config, consistent with the layering rule. The high-connectivity node VerdictNeeds changes — nothing here is blocking correctness of the workflow fix, and the single Warning is about discoverability rather than a bug: the This review was generated by an AI assistant. |
|
Thanks for putting this together, @andreatgretel—the release-resiliency work is thoughtful, and I found a few cross-workflow edge cases worth tightening before merge. SummaryThis PR decouples Fern release snapshotting/publishing from notebook execution, adds retry and provenance handling for notebooks, restores rolling Dev Notes and Recipes, and introduces a notebook-CI model-probe bypass. The implementation largely matches the stated intent, but the cache and fallback paths can publish notebooks from the wrong execution context or regress them later, and cancellation no longer reliably stops deployment. FindingsWarnings — Worth addressing
What Looks Good
VerdictNeeds changes — please address the execution-profile cache mismatch, provenance-aware Dev Notes reuse, and cancellation guard before merge. This review was generated by an AI assistant. |
|
@nabinchha Thanks, these were good catches. I reworked the flow as follows:
Cache provenance now includes an explicit execution profile, separating scheduled 2-record runs from 5-record release runs. The profile, Makefile, and notebook builder are included in both the cache key and per-notebook fingerprint. Artifact seeding only accepts matching fingerprints and does not overwrite valid cached notebooks. Dev Notes no longer search older successful workflow artifacts. Each full release stores its rendered notebooks as a checksummed GitHub Release asset, while The fallback is recoverable without creating another release: manually rerunning Build Fern docs for the same tag replaces the published snapshot when notebook execution succeeds. The existing Validation: 33 docs tests pass, workflow YAML and shell syntax validate, and both generated and restored Fern checks report 0 errors. |
2 participants
📋 Summary
Ensures every DataDesigner release publishes an actual
vX.Y.ZFern docs version even when external model providers make notebook execution fail. It also keeps Latest's Dev Notes and Recipes rolling frommain, preserves frozen release content, and restores reliable manual workflow dispatch.🔗 Related Issue
N/A - requested from the DataDesigner docs release discussion.
🔄 Changes
mainduring the release transaction without changing frozen version navigation, pages, or release metadata.setup-uvv8.1.0 after a workflow-dispatch bisect confirmed v8.3.x fails before creating a job; checkout v7 remains enabled.🔍 Attention Areas
build-fern-docs.yml- intentionally publishes source notebooks if execution fails so the versioned release still goes live.build-notebooks.yml- accepts cached artifacts only with matching source and runtime fingerprints.readiness.py- the new model-probe bypass is enabled only by the notebook CI environment; real notebook generation calls still run.🧪 Testing
make testpasses (not run locally; the full GitHub CI matrix passes)make check-fern-docs-locallypasses✅ Checklist