docs: move Compatibility section

Author: dinohamzic

.vscode/compatibility-update-summary.md

@@ -0,0 +1,123 @@
+# JupyterLab Compatibility Documentation Update
+
+## Summary
+
+This update documents JupyterLab version compatibility, adds maintenance plans, and implements dependency safeguards to prevent breaking changes.
+
+## Changes Made
+
+### 1. README.md - Added Comprehensive Compatibility Section
+
+- **Updated Requirements**: Changed from "JupyterLab 4.5.0 or higher" to "JupyterLab >= 4.4.0, < 5.0.0"
+  - More accurate (content provider registry available from 4.4.0)
+  - Includes upper bound to prevent JupyterLab 5.x installation
+
+- **Added Compatibility Section** with three subsections:
+  - **JupyterLab Version Support**: Documents the 4.4.0+ requirement and upper bound
+  - **Maintenance Policy**:
+    - Explains semantic versioning for releases
+    - Provides clear plan for JupyterLab 5.x support
+    - References official JupyterLab extension guidelines
+  - **Backwards Compatibility**:
+    - Documents pre-release status (0.x.x)
+    - Explains commitment to semver from 1.0.0 onwards
+    - Notes that JupyterLab 3.x is not supported
+
+### 2. pyproject.toml - Updated JupyterLab Requirements
+
+- **Build system**: Updated from `jupyterlab>=4.0.0,<5` to `jupyterlab>=4.4.0,<5`
+- **Release hooks**: Updated from `jupyterlab>=4.0.0,<5` to `jupyterlab>=4.4.0,<5`
+
+### 3. package.json - Added Upper Bounds to Dependencies
+
+Added explicit upper bounds to all `@jupyterlab` dependencies to prevent breaking changes:
+
+```json
+"dependencies": {
+  "@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"
+}
+```
+
+```json
+"devDependencies": {
+  "@jupyterlab/builder": "^4.0.0 <5",
+  "@jupyterlab/testutils": "^4.0.0 <5"
+}
+```
+
+### 4. src/index.ts - Updated Comment
+
+- Changed outdated comment about JupyterLab <4.4 support
+- Added clear error message indicating 4.4.0+ requirement
+
+### 5. CONTRIBUTING.md - Updated Versioning Section
+
+- Updated examples to reflect actual 4.4.0+ requirement
+- Documented the upper bounds strategy
+- Added reference to JupyterLab extension development best practices
+
+## Rationale
+
+### Why JupyterLab 4.4.0+?
+
+The extension uses the **content provider registry API** which was introduced in JupyterLab 4.4. This is not optional - the extension cannot function without it.
+
+### Why Upper Bounds?
+
+Following [JupyterLab's extension development guidelines](https://jupyterlab.readthedocs.io/en/stable/extension/extension_dev.html#overview-of-extensions):
+
+> Consider documenting your maintenance plans to users in your project, or setting an upper bound on the version of JupyterLab your extension is compatible with in your project's package metadata.
+
+Upper bounds prevent:
+
+- Automatic installation with incompatible future major versions
+- Breaking changes from affecting users unexpectedly
+- Support burden from untested versions
+
+### Backwards Compatibility
+
+Since this is version 0.1.0 (pre-release), there's no backwards compatibility to maintain yet. However, the documentation now clearly states:
+
+- Current status: APIs may change in 0.x.x versions
+- Future commitment: Semantic versioning from 1.0.0 onwards
+
+## Issue #22 - Dependency Breaking Changes
+
+This update addresses the concern about checking dependencies for breaking changes:
+
+1. ✅ All `@jupyterlab` dependencies now have upper bounds
+2. ✅ Version requirements accurately reflect actual needs (4.4.0+)
+3. ✅ Maintenance policy documented for future major version updates
+4. ✅ Users are informed about compatibility through README
+
+## Testing Recommendations
+
+Before releasing these changes:
+
+1. Verify the extension builds successfully:
+
+   ```bash
+   jlpm build:prod
+   ```
+
+2. Test with JupyterLab 4.4.x:
+
+   ```bash
+   pip install 'jupyterlab>=4.4.0,<4.5.0'
+   ```
+
+3. Verify installation fails gracefully with JupyterLab <4.4 or >=5.0
+
+## Next Steps
+
+When JupyterLab 5.x is released:
+
+1. Review JupyterLab 5.x migration guide
+2. Test extension with JupyterLab 5.x alpha/beta
+3. Update dependencies if compatible
+4. If breaking changes required, release as new major version
+5. Document changes in CHANGELOG.md