docs: update OSS docs #34
Conversation
📝 WalkthroughWalkthroughAdds a new CONTRIBUTING.md with step-by-step developer guidance: environment setup (Python/Node, uv tooling), editable installs, authentication for @deepnote/blocks, linking the frontend with JupyterLab, enabling the server extension, watch/build/debug workflows, test commands (pytest/Jest), uninstall steps, release guidance, and instructions for applying extension template updates. README.md was refocused to user-facing install/usage/troubleshooting content and now links to CONTRIBUTING.md for development. RELEASE.md was updated to state only the Python package is published to PyPI and the frontend is not published separately. Sequence Diagram(s)The changes are documentation-only and do not introduce or modify runtime control flow, so no sequence diagram is provided. Possibly related PRs
Pre-merge checks❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (2)
CONTRIBUTING.md(1 hunks)README.md(0 hunks)
💤 Files with no reviewable changes (1)
- README.md
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
CONTRIBUTING.md
31-31: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
36-36: Bare URL used
(MD034, no-bare-urls)
42-42: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
44-44: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
Signed-off-by: Andy Jakubowski <hello@andyjakubowski.com>
Signed-off-by: Andy Jakubowski <hello@andyjakubowski.com>
andyjakubowski
force-pushed
the
andy/grn-4956-update-oss-docs
branch
from
d270a96 to
e34145a
Compare
Signed-off-by: Andy Jakubowski <hello@andyjakubowski.com>
andyjakubowski
requested review from
Artmann,
jamesbhobbs and
saltenasl
as code owners
andyjakubowski
changed the base branch from
andy/grn-4810-default-to-python3-kernel
to
main
andyjakubowski
dismissed
coderabbitai[bot]’s stale review
The base branch was changed.
Signed-off-by: Andy Jakubowski <hello@andyjakubowski.com>
|
The author of this PR, andyjakubowski, is not an activated member of this organization on Codecov. |
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (1)
README.md(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: build
- GitHub Check: check_release
🔇 Additional comments (3)
README.md (3)
6-6: User-focused content structure is clear and well-organized.The reorganization successfully shifts README toward end-user guidance: simplified install, clear usage examples, and straightforward uninstall steps. Good alignment with PR objectives.
Also applies to: 15-19, 21-27, 49-55
57-59: Contributing reference appropriately delegates to external file.Clean pointer to CONTRIBUTING.md aligns with separation of concerns (user README vs. contributor guide).
10-11: Confirm if Python 3.9+ is intentional or should align with JupyterLab 4.0.0's 3.8+ baseline.JupyterLab 4.0.0 requires Python 3.8 or newer, but the README specifies 3.9+. If this stricter requirement reflects extension-specific dependencies, keep it; otherwise, consider relaxing to 3.8+ to match the JupyterLab baseline.
Signed-off-by: Andy Jakubowski <hello@andyjakubowski.com>
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
README.md (1)
29-43: Expand Troubleshooting with diagnostic steps and support link.The section verifies extension presence but omits common diagnostic actions (browser cache, console errors, logs) and a link to open issues—improvements suggested in prior review.
Consider this more complete guidance:
## Troubleshooting If you encounter issues with the extension, verify that both the server and frontend extensions are properly installed and enabled. Check server extensions: ```bash jupyter server extension listCheck frontend extensions:
jupyter labextension list
- If issues persist:
- Clear your browser cache and reload JupyterLab.
- Open the browser console (F12 or Ctrl+Shift+I) and check for errors.
- Check Jupyter server logs for backend errors.
- For further assistance, please open an issue on GitHub.
</blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used**: CodeRabbit UI **Review profile**: ASSERTIVE **Plan**: Pro <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between cce9f5647f9e0ae7982d4e8c7360b6731f2bd3d5 and fd857e123b9fd661b1edb3888b03a8c84a85c3b9. </details> <details> <summary>📒 Files selected for processing (1)</summary> * `README.md` (1 hunks) </details> <details> <summary>⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)</summary> * GitHub Check: build * GitHub Check: check_release </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Conda should not be a recommended package registry target Signed-off-by: Andy Jakubowski <hello@andyjakubowski.com>
We need that version because it adds support for custom content providers, something our extension depends on: https://jupyterlab.readthedocs.io/en/stable/extension/extension_points.html#content-provisioning Signed-off-by: Andy Jakubowski <hello@andyjakubowski.com>
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (1)
README.md(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Spell Check
- GitHub Check: build
- GitHub Check: check_release
🔇 Additional comments (2)
README.md (2)
10-11: Clarify the 4.5.0 baseline and add support/maintenance policy.The Requirements bump JupyterLab from 4.0.0 to 4.5.0 without explanation. Past feedback flagged vague maintenance guidance; the README now lacks explicit support scope (which 4.x releases are supported, what happens if users stay on older versions, breaking-change expectations).
Consider adding a brief maintenance note:
## Requirements - Python 3.9 or higher - - JupyterLab 4.5.0 or higher + - JupyterLab 4.5.0 or higher (tested minimum; all 4.x releases supported) + + **Maintenance:** We recommend keeping JupyterLab updated to the latest 4.x for bug fixes and security patches. Breaking changes will be called out in release notes and may require upgrading to 5.x.
53-55: Clean separation of user and developer docs.The Contributing section now appropriately directs users to CONTRIBUTING.md for development guidance, keeping README focused on usage. This aligns well with the PR objectives.
jamesbhobbs
left a comment
jamesbhobbs
left a comment
There was a problem hiding this comment.
Not final but a vast improvement on what we have @Yggdrasill501 should be updating it soon so merging as is for the improvement.
Closes:
GRN-4812: Update README.md
GRN-4817: Create a contributing guide
GRN-4921: Add instructions on applying extension template updates
Signed-off-by: Andy Jakubowski hello@andyjakubowski.com
Summary by CodeRabbit