docs: Add docs for .deepnote file sync feature#334
Conversation
|
Note Reviews pausedUse the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughA single-line manifest update in CLAUDE.md replaced a missing reference with "AGENTS.md". A new documentation file, docs/deepnote-file-sync.md, was added describing Deepnote's file sync feature: exporting a project to a portable Sequence Diagram(s)sequenceDiagram
participant Dev as Developer
participant Deepnote as Deepnote Cloud
participant File as .deepnote (portable file)
participant Local as Local FS / Editor
Dev->>Deepnote: Request export (create .deepnote)
Deepnote-->>File: Generate portable YAML
Deepnote-->>Dev: Provide download link
Dev->>Local: Save / edit .deepnote
Local->>Dev: Edit notebooks/blocks
Dev->>Deepnote: Import / Link .deepnote
Deepnote->>File: Read project contents
Deepnote-->>Dev: Confirm link established
Note over Deepnote,Local: Bidirectional sync
Deepnote->>Local: Push automatic/manual changes
Local->>Deepnote: Push local changes (manual sync)
Deepnote-->>Dev: Show sync status / conflicts
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 🚥 Pre-merge checks | ✅ 3 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #334 +/- ##
=======================================
Coverage 83.42% 83.42%
=======================================
Files 122 122
Lines 7355 7355
Branches 2040 2040
=======================================
Hits 6136 6136
Misses 1219 1219 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/deepnote-file-sync.md`:
- Around line 55-63: Clarify the distinction between automatic and manual sync:
update the text around the "Auto-sync" and "Manual sync" sections to explicitly
state that Deepnote's UI Git actions (e.g., using the Deepnote branch switcher
or the built-in Git pull within the Deepnote UI) trigger automatic sync of
notebooks into the linked `.deepnote` file, whereas external Git operations
performed outside the UI (e.g., running `git pull` or `git checkout` in your
terminal or via scripts/CI) do not trigger auto-sync and therefore require the
user to run the "Sync from file" manual action from the project menu or file
ribbon; also make a short note that "Sync to file" is used to push project
changes back into the `.deepnote` file.
ℹ️ Review info
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
CLAUDE.mddocs/deepnote-file-sync.md
…of github.com:deepnote/deepnote into oleh/blu-5714-add-public-documentation-about-git-sync
There was a problem hiding this comment.
♻️ Duplicate comments (1)
docs/deepnote-file-sync.md (1)
55-56:⚠️ Potential issue | 🟡 MinorScope auto-sync triggers to Deepnote UI actions explicitly.
This still reads as if any
git pull/ branch switch auto-syncs. Please explicitly say this applies to Git actions performed in Deepnote UI, while external terminal/script Git actions require Sync from file.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/deepnote-file-sync.md` around lines 55 - 56, Update the sentence that currently reads "Similarly, when you pull from a remote Git repository or switch to a different branch, Deepnote will sync notebooks from the file into the linked Deepnote Cloud project." to explicitly scope auto-sync to Git actions performed in the Deepnote UI; state that only Git operations done through Deepnote's interface will trigger automatic syncing and that Git actions performed externally (terminal/scripts) will not auto-sync and instead require using the "Sync from file" action. Ensure you reference the phrase "pull from a remote Git repository or switch to a different branch" and the "Sync from file" action so readers clearly understand the distinction.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@docs/deepnote-file-sync.md`:
- Around line 55-56: Update the sentence that currently reads "Similarly, when
you pull from a remote Git repository or switch to a different branch, Deepnote
will sync notebooks from the file into the linked Deepnote Cloud project." to
explicitly scope auto-sync to Git actions performed in the Deepnote UI; state
that only Git operations done through Deepnote's interface will trigger
automatic syncing and that Git actions performed externally (terminal/scripts)
will not auto-sync and instead require using the "Sync from file" action. Ensure
you reference the phrase "pull from a remote Git repository or switch to a
different branch" and the "Sync from file" action so readers clearly understand
the distinction.
ℹ️ Review info
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
docs/deepnote-file-sync.md
dinohamzic
left a comment
There was a problem hiding this comment.
Looking good, left suggestions for possible improvements.
| If you already have a `.deepnote` file (for example, from a cloned repository): | ||
|
|
||
| 1. Navigate to the file in your project's file browser | ||
| 2. Click on the file menu (three dots) and select **Import project from file and link** |
There was a problem hiding this comment.
Import project from file and link
This sentence is a bit hard to parse, I first thought "link" meant "url", instead of the verb "to link". But I have no good suggestions on how to improve the phrasing.
There was a problem hiding this comment.
It's name of the menu item in the UI, so we should use exact name. Also, it will be highlighted in bold when rendered to denote it's an label in the UI and not part of instructions
There was a problem hiding this comment.
Yes I understand, my comment was indeed referencing the UI label, which is a bit confusing.
docs/deepnote-file-sync.md
Outdated
| The sync includes: | ||
|
|
||
| - Project name | ||
| - All notebooks and blocks inside them |
There was a problem hiding this comment.
What does "them" reference here? Would the phrasing below be better?
| - All notebooks and blocks inside them | |
| - All notebooks and blocks in the project |
There was a problem hiding this comment.
Blocks belong to notebooks, not to project, so I don't think your suggestion will be correct
There was a problem hiding this comment.
In that case I'd keep it simple as "All notebooks and blocks"
Co-authored-by: Dino Hamzić <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (3)
docs/deepnote-file-sync.md (3)
55-55:⚠️ Potential issue | 🟡 MinorAuto-sync trigger still ambiguous.
"pull from a remote Git repository" doesn't distinguish Deepnote UI actions from external terminal operations. Past comment asked for explicit distinction; partially addressed in line 63 but line 55 remains unclear.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/deepnote-file-sync.md` at line 55, Clarify that the phrase "pull from a remote Git repository" refers to Deepnote's built-in Git integration actions vs external git commands: update the sentence containing "pull from a remote Git repository" and "switch to a different branch" to explicitly state "when you use Deepnote's Git integration (e.g., Deepnote UI pull/branch switch) or when you perform the same actions externally (e.g., git pull or git checkout in a terminal), Deepnote will sync notebooks..." so readers can tell UI-triggered syncs from terminal-triggered syncs; keep both examples (Deepnote UI vs external terminal) in the same sentence for clarity.
70-70: 🧹 Nitpick | 🔵 TrivialMinor pronoun clarity.
"inside them" works but is slightly less direct. Past reviewer suggested simpler phrasing.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/deepnote-file-sync.md` at line 70, Replace the phrase "All notebooks and blocks inside them" with a clearer, more direct wording such as "All notebooks and their blocks" (locate the exact string "All notebooks and blocks inside them" in docs/deepnote-file-sync.md and update it accordingly).
40-40:⚠️ Potential issue | 🟡 MinorPhrasing remains ambiguous.
"link" at end of sentence can read as noun (URL) rather than verb. Past reviewer noted same confusion.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/deepnote-file-sync.md` at line 40, The phrasing "Import project from file and link" is ambiguous; update the sentence to clearly indicate the action (e.g., change the menu option text to "Import project from file and link to an existing project" or "Import project from file and link it") so "link" reads as a verb and not a noun—locate the string "Import project from file and link" in docs/deepnote-file-sync.md and replace it with the chosen explicit wording.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/deepnote-file-sync.md`:
- Line 63: The phrase "programmatically from the notebook" in the "**Sync from
file** — Pull changes..." sentence is ambiguous; update that sentence (the
"**Sync from file**" line) to clarify by replacing "or programmatically from the
notebook" with clearer wording such as "or via scripts/commands run outside the
Deepnote UI (for example, from your terminal or automation scripts)" so readers
understand it refers to external script/terminal operations rather than running
commands inside Deepnote.
---
Duplicate comments:
In `@docs/deepnote-file-sync.md`:
- Line 55: Clarify that the phrase "pull from a remote Git repository" refers to
Deepnote's built-in Git integration actions vs external git commands: update the
sentence containing "pull from a remote Git repository" and "switch to a
different branch" to explicitly state "when you use Deepnote's Git integration
(e.g., Deepnote UI pull/branch switch) or when you perform the same actions
externally (e.g., git pull or git checkout in a terminal), Deepnote will sync
notebooks..." so readers can tell UI-triggered syncs from terminal-triggered
syncs; keep both examples (Deepnote UI vs external terminal) in the same
sentence for clarity.
- Line 70: Replace the phrase "All notebooks and blocks inside them" with a
clearer, more direct wording such as "All notebooks and their blocks" (locate
the exact string "All notebooks and blocks inside them" in
docs/deepnote-file-sync.md and update it accordingly).
- Line 40: The phrasing "Import project from file and link" is ambiguous; update
the sentence to clearly indicate the action (e.g., change the menu option text
to "Import project from file and link to an existing project" or "Import project
from file and link it") so "link" reads as a verb and not a noun—locate the
string "Import project from file and link" in docs/deepnote-file-sync.md and
replace it with the chosen explicit wording.
ℹ️ Review info
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
docs/deepnote-file-sync.md
|
@coderabbitai pause |
There was a problem hiding this comment.
♻️ Duplicate comments (1)
docs/deepnote-file-sync.md (1)
63-63:⚠️ Potential issue | 🟡 MinorClarify "programmatically from the notebook."
This phrase is ambiguous. Does it mean running git commands in notebook cells or automated scripts outside Deepnote UI?
Suggest: "if you performed it from your terminal or via scripts run outside the Deepnote UI."
✏️ Proposed fix
-- **Sync from file** — Pull changes from the file into your project. Use this after `git pull` or `git checkout` if you performed it from your machine's terminal or programmatically from the notebook. +- **Sync from file** — Pull changes from the file into your project. Use this after `git pull` or `git checkout` if you performed it from your terminal or via scripts run outside the Deepnote UI.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/deepnote-file-sync.md` at line 63, Update the sentence in the "**Sync from file** — Pull changes from the file into your project." line to remove the ambiguous phrase "programmatically from the notebook." Replace it with a clearer wording such as "if you performed it from your terminal or via scripts run outside the Deepnote UI" so the full sentence reads: pull after `git pull` or `git checkout` if you performed it from your terminal or via scripts run outside the Deepnote UI; locate the "**Sync from file**" line in the doc to make this change.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@docs/deepnote-file-sync.md`:
- Line 63: Update the sentence in the "**Sync from file** — Pull changes from
the file into your project." line to remove the ambiguous phrase
"programmatically from the notebook." Replace it with a clearer wording such as
"if you performed it from your terminal or via scripts run outside the Deepnote
UI" so the full sentence reads: pull after `git pull` or `git checkout` if you
performed it from your terminal or via scripts run outside the Deepnote UI;
locate the "**Sync from file**" line in the doc to make this change.
ℹ️ Review info
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
docs/deepnote-file-sync.md
✅ Actions performedReviews paused. |
|
@coderabbitai approve |
✅ Actions performedComments resolved and changes approved. |
Summary by CodeRabbit