docs: compatibility and maintenance plans

[dinohamzic]

Summary by CodeRabbit

• Documentation

  • Clarified compatibility: requires JupyterLab >=4.4.0, <5.0.0
  • Added Compatibility, Maintenance Policy, Backwards Compatibility, and Compatibility note for unsupported older majors
  • Clarified messaging when required platform features are missing

• Chores

  • Tightened dependency and build-tool version ranges with upper bounds to avoid incompatible major upgrades
  • Updated recommended template update workflow to a trusted update and review process

[linear]

GRN-4927 Document JupyterLab version compatibility and maintenance plans

Update README with this information.

From https://jupyterlab.readthedocs.io/en/stable/extension/extension_dev.html#overview-of-extensions:

Your extensions may break with new releases of JupyterLab. As noted in Backwards Compatibility, Versions and Breaking Changes, JupyterLab development and release cycles follow semantic versioning, so we recommend planning your development process to account for possible future breaking changes that may disrupt users of your 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.

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request standardizes version constraints and documentation across the extension. It raises the minimum JupyterLab requirement to 4.4.0, adds explicit upper bounds (e.g., <5) to all JupyterLab-related dependencies in package.json and pyproject.toml, converts some package.json peerDependencies to dependencies, updates build hooks and pre-build install commands to require jupyterlab>=4.4.0,<5, updates CONTRIBUTING to prefer copier update --trust with review guidance, and adds Compatibility/Maintenance/Backwards-compatibility sections to README. src/index.ts now requires the content provider registry and updates the runtime error message accordingly.

Sequence Diagram(s)

sequenceDiagram
  participant App as JupyterLab App
  participant Plugin as Extension Plugin
  participant Registry as ContentProviderRegistry

  rect rgba(200,230,255,0.35)
    App->>Plugin: activate(plugin)
    Plugin->>Registry: check existence of content provider registry
  end

  alt Registry present (JupyterLab ≥ 4.4.0)
    Registry-->>Plugin: registry object
    Plugin->>App: register content provider / proceed
  else Registry missing (JupyterLab < 4.4.0)
    Plugin-->>App: throw Error("Content provider registry required — JupyterLab 4.4.0 or higher")
  end

Loading

Pre-merge checks

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title "docs: compatibility and maintenance plans" is partially related to the changeset. It accurately describes a significant portion of the PR—the new documentation sections in README.md covering compatibility, maintenance policy, and backwards compatibility. However, the title emphasizes only the documentation aspect while the PR also includes substantial dependency version constraint updates across package.json, pyproject.toml, and src/index.ts, along with corresponding code comments in src/index.ts. The "docs:" prefix could be misleading since the primary technical change (bumping JupyterLab minimum version to 4.4.0 with upper bounds) is not purely documentation. Despite this, the title refers to a real aspect of the change and meets the criteria for partial relatedness.

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d63124e and e4c2eea.

⛔ Files ignored due to path filters (1)

• yarn.lock is excluded by !**/yarn.lock, !**/*.lock

📒 Files selected for processing (3)

• CONTRIBUTING.md (1 hunks)
• README.md (2 hunks)
• package.json (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: build
• GitHub Check: Audit - Production
• GitHub Check: check_release

🔇 Additional comments (7)

package.json (2)

63-67: Version constraints now correctly enforce 4.4.0 minimum.

The dependencies have been updated from permissive ranges (e.g., ^4.0.0) to explicit 4.4.0+ with upper bounds, aligning with the content provider registry API requirement. This resolves the earlier critical issue flagged in past review.

Ranges are consistent and clear: JupyterLab packages use ^4.4.0 <5, coreutils uses ^6.0.0 <7, services uses ^7.0.0 <8.

However, verify that @jupyterlab/notebook is intentionally pinned to ^4.4.7 rather than ^4.4.0. Is there a specific reason for the minor version bump?

---

74-75: DevDependencies correctly updated to match production constraints.

@jupyterlab/builder and @jupyterlab/testutils now use ^4.4.0 <5, maintaining consistency with the 4.4.0+ requirement across the build and test toolchain.

README.md (3)

11-11: Requirements section correctly specifies version bounds.

Line 11 clearly communicates the supported JupyterLab range: >= 4.4.0, < 5.0.0. Explicit syntax avoids ambiguity.

---

53-73: Compatibility and Maintenance sections provide clear guidance.

The new Compatibility section (lines 53–59) explains the 4.4.0 requirement and rationale for upper bounds. The Maintenance Policy section (lines 61–73) documents semver principles and future JupyterLab 5.x support planning, aligning with extension best practices.

---

75-82: Backwards Compatibility section sets realistic expectations.

Clearly distinguishes pre-release status (0.x.x) from future stable releases (1.0.0+) and documents non-support for JupyterLab 3.x. Helps users understand API stability guarantees.

CONTRIBUTING.md (2)

149-170: Versioning section accurately documents build and dependency constraints.

Clearly states the 4.4.0+ requirement and upper-bound rationale. Build-system and package.json examples are current and match the project's actual constraints, making it straightforward for contributors to align their environment.

---

177-180: Copier update command uses --trust flag with review guidance.

Changing from copier update to copier update --trust streamlines the workflow. The added guidance to "review and commit updates as appropriate" mitigates risk by empowering contributors to validate changes before merging.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 69.56%. Comparing base (b669930) to head (e4c2eea).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #50   +/-   ##
=======================================
  Coverage   69.56%   69.56%           
=======================================
  Files          13       13           
  Lines         253      253           
  Branches       28       28           
=======================================
  Hits          176      176           
  Misses         73       73           
  Partials        4        4           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b669930 and c33e821.

📒 Files selected for processing (5)

• CONTRIBUTING.md (1 hunks)
• README.md (1 hunks)
• package.json (1 hunks)
• pyproject.toml (2 hunks)
• src/index.ts (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). (1)

• GitHub Check: check_release

🔇 Additional comments (10)

pyproject.toml (2)

2-2: LGTM!

Build-system constraint properly reflects the 4.4.0 minimum requirement.

---

81-81: Consistent with build-system requirements.

The before-build-npm hook correctly uses the same version constraint as the build-system requires.

package.json (1)

74-75: Consistent with dependencies approach.

DevDependencies follow the same explicit upper bound pattern as dependencies.

src/index.ts (2)

30-30: Helpful context for developers.

The comment clearly explains why JupyterLab 4.4+ is required.

---

35-35: Clear and actionable error message.

The error message specifies the exact minimum version requirement.

README.md (3)

11-11: Specific version requirement is clear.

The requirement matches the version constraints in package.json and pyproject.toml.

---

13-20: Comprehensive compatibility explanation.

The section clearly explains both the minimum requirement and the rationale for the upper bound.

---

21-42: Well-structured maintenance and compatibility documentation.

The sections clearly explain semantic versioning policy, JupyterLab 5.x plans, and current pre-release status. The warning that 0.x.x APIs may change without notice is important context for users.

CONTRIBUTING.md (2)

149-156: Clear versioning guidance for contributors.

The requirement and rationale are well-explained, with an accurate pyproject.toml example.

---

158-171: Helpful example with authoritative reference.

The package.json example matches the actual file, and the link to JupyterLab's extension development best practices provides authoritative support for the upper bounds approach.

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c33e821 and d63124e.

⛔ Files ignored due to path filters (1)

• yarn.lock is excluded by !**/yarn.lock, !**/*.lock

📒 Files selected for processing (5)

• CONTRIBUTING.md (1 hunks)
• README.md (2 hunks)
• package.json (1 hunks)
• pyproject.toml (2 hunks)
• src/index.ts (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 (5)

pyproject.toml (1)

2-2: LGTM—version constraints align with 4.4.0 requirement.

The build-system and pre-build hook now correctly enforce JupyterLab >=4.4.0,<5.

Also applies to: 81-81

src/index.ts (1)

30-30: LGTM—messaging clarifies 4.4.0 requirement.

Comment and error message accurately reflect the content provider registry dependency.

Also applies to: 35-35

README.md (1)

11-11: LGTM—comprehensive compatibility documentation.

Requirements and maintenance policy are clearly stated. Upper bound rationale is well-explained.

Also applies to: 53-83

CONTRIBUTING.md (2)

161-168: Example reflects package.json's incorrect constraints.

The snippet shows "@jupyterlab/application": "^4.0.0 <5", which permits versions before 4.4.0. Once package.json is corrected to ^4.4.0 <5, update this example accordingly.

---

177-180: LGTM—copier command updated appropriately.

The --trust flag enables automated template application. Guidance to review and commit is clear.