docs: compatibility and maintenance plans

Author: dinohamzic

CONTRIBUTING.md

@@ -146,25 +146,29 @@ jlpm test
 
 We follow [Semantic Versioning (semver)](https://semver.org/).
 
-The extension pins JupyterLab to the current major version in both Python and JavaScript dependencies to ensure compatibility.
+The extension requires **JupyterLab 4.4.0 or higher** (but not JupyterLab 5.x) due to its dependency on the content provider registry API. All JupyterLab dependencies include upper bounds to prevent automatic installation with incompatible future major versions.
 
-**Example `pyproject.toml` dependency:**
+**Current `pyproject.toml` build requirement:**
 
 ```toml
-[project.optional-dependencies]
-jupyterlab = ["jupyterlab>=4.0.0,<5.0.0"]
+[build-system]
+requires = ["hatchling>=1.5.0", "jupyterlab>=4.4.0,<5", "hatch-nodejs-version>=0.3.2"]
 ```
 
-**Example `package.json` peerDependencies:**
+**Current `package.json` dependencies with upper bounds:**
 
 ```json
-  "peerDependencies": {
-    "@jupyterlab/application": "^4.0.0",
-    "@jupyterlab/apputils": "^4.0.0",
-    "jupyterlab": "^4.0.0"
+  "dependencies": {
+    "@jupyterlab/application": "^4.0.0 <5",
+    "@jupyterlab/notebook": "^4.4.7 <5",
+    "@jupyterlab/services": "^7.0.0 <8",
+    "@jupyterlab/coreutils": "^6.0.0 <7",
+    ...
   }
 ```
 
+These upper bounds help prevent breaking changes from affecting users and align with JupyterLab's [extension development best practices](https://jupyterlab.readthedocs.io/en/stable/extension/extension_dev.html#overview-of-extensions).
+
 ## Sync with the JupyterLab extension template
 
 This project was bootstrapped using the [JupyterLab extension template](https://github.com/jupyterlab/extension-template). To keep your project up to date with improvements and best practices from the template, run:

README.md

@@ -8,7 +8,38 @@ Read‑only viewer for Deepnote `.deepnote` files inside JupyterLab.
 ## Requirements
 
 - Python 3.9 or higher
-- JupyterLab 4.5.0 or higher
+- JupyterLab >= 4.4.0, < 5.0.0
+
+## Compatibility
+
+### JupyterLab Version Support
+
+This extension is compatible with **JupyterLab 4.4.0 or higher** (specifically JupyterLab 4.x series). It requires the content provider registry API introduced in JupyterLab 4.4.
+
+**Upper bound:** The extension sets an upper bound of `< 5.0.0` to prevent automatic installation with potentially incompatible future major versions of JupyterLab.
+
+### Maintenance Policy
+
+Following [JupyterLab's extension development guidelines](https://jupyterlab.readthedocs.io/en/stable/extension/extension_dev.html#overview-of-extensions), we adhere to semantic versioning principles:
+
+- **Major releases** (e.g., 1.0.0 → 2.0.0): May introduce breaking changes and require user action
+- **Minor releases** (e.g., 1.0.0 → 1.1.0): Add new features while maintaining backwards compatibility
+- **Patch releases** (e.g., 1.0.0 → 1.0.1): Bug fixes and minor improvements only
+
+When JupyterLab 5.x is released, we will:
+
+1. Evaluate the changes and update the extension as needed
+2. Release a new major or minor version with explicit JupyterLab 5.x support
+3. Clearly document any breaking changes in the changelog
+
+### Backwards Compatibility
+
+This extension follows semantic versioning for its own API:
+
+- **Current version (0.x.x)**: Pre-release phase. APIs may change without prior notice.
+- **Version 1.0.0 onwards**: We will maintain backwards compatibility within major versions and clearly document breaking changes between major versions.
+
+Note: This extension does **not** support JupyterLab 3.x or earlier versions.
 
 ## Install
 

package.json

@@ -60,19 +60,19 @@
     },
     "dependencies": {
         "@deepnote/blocks": "^1.1.0",
-        "@jupyterlab/application": "^4.0.0",
-        "@jupyterlab/coreutils": "^6.0.0",
-        "@jupyterlab/notebook": "^4.4.7",
-        "@jupyterlab/services": "^7.0.0",
-        "@jupyterlab/settingregistry": "^4.0.0",
+        "@jupyterlab/application": "^4.0.0 <5",
+        "@jupyterlab/coreutils": "^6.0.0 <7",
+        "@jupyterlab/notebook": "^4.4.7 <5",
+        "@jupyterlab/services": "^7.0.0 <8",
+        "@jupyterlab/settingregistry": "^4.0.0 <5",
         "@lumino/widgets": "^2.7.1",
         "lodash": "^4.17.21",
         "yaml": "^2.8.1",
         "zod": "^4.1.11"
     },
     "devDependencies": {
-        "@jupyterlab/builder": "^4.0.0",
-        "@jupyterlab/testutils": "^4.0.0",
+        "@jupyterlab/builder": "^4.0.0 <5",
+        "@jupyterlab/testutils": "^4.0.0 <5",
         "@types/jest": "^29.2.0",
         "@types/json-schema": "^7.0.11",
         "@types/lodash": "^4.17.20",

pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["hatchling>=1.5.0", "jupyterlab>=4.0.0,<5", "hatch-nodejs-version>=0.3.2"]
+requires = ["hatchling>=1.5.0", "jupyterlab>=4.4.0,<5", "hatch-nodejs-version>=0.3.2"]
 build-backend = "hatchling.build"
 
 [project]
@@ -78,7 +78,7 @@ version_cmd = "hatch version"
 
 [tool.jupyter-releaser.hooks]
 before-build-npm = [
-    "python -m pip install 'jupyterlab>=4.0.0,<5'",
+    "python -m pip install 'jupyterlab>=4.4.0,<5'",
     "jlpm",
     "jlpm build:prod"
 ]

src/index.ts

@@ -27,12 +27,12 @@ const plugin: JupyterFrontEndPlugin<void> = {
     toolbarRegistry: IToolbarWidgetRegistry
   ) => {
     // Register a custom contents provider for the default notebook widget factory.
+    // Note: Content provider registry is required (available in JupyterLab 4.4+)
     const drive = (app.serviceManager.contents as ContentsManager).defaultDrive;
     const registry = drive?.contentProviderRegistry;
     if (!registry) {
-      // If content provider is a non-essential feature and support for JupyterLab <4.4 is desired:
       console.error(
-        'Cannot initialize content provider: no content provider registry.'
+        'Cannot initialize content provider: no content provider registry. JupyterLab 4.4.0 or higher is required.'
       );
       return;
     }