docs: update README, CONTRIBUTING, RELEASE

Signed-off-by: Andy Jakubowski <[email protected]>

Author: andyjakubowski

CONTRIBUTING.md

@@ -1,3 +1,7 @@
+# Scope
+
+This document is intended for contributors and maintainers working on the extension's source code. For general usage and installation instructions, please refer to the README.
+
 # Contributing to `jupyterlab-deepnote`
 
 ## Development install
@@ -138,6 +142,39 @@ jlpm
 jlpm test
 ```
 
-## Packaging the extension
+## Versioning and compatibility
+
+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.
+
+**Example `pyproject.toml` dependency:**
+
+```toml
+[project.optional-dependencies]
+jupyterlab = ["jupyterlab>=4.0.0,<5.0.0"]
+```
+
+**Example `package.json` peerDependencies:**
+
+```json
+  "peerDependencies": {
+    "@jupyterlab/application": "^4.0.0",
+    "@jupyterlab/apputils": "^4.0.0",
+    "jupyterlab": "^4.0.0"
+  }
+```
+
+## 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:
+
+```sh
+copier update --trust
+```
+
+This will apply the latest template changes interactively. Review and commit any updates as appropriate.
+
+## Release workflow
 
-See [RELEASE](RELEASE.md)
+See [RELEASE](RELEASE.md) for details on the release process. We recommend using [Jupyter Releaser](https://github.com/jupyter-server/jupyter_releaser) and [PyPI trusted publishing](https://docs.pypi.org/trusted-publishers/) for secure and automated releases.

README.md

@@ -3,44 +3,57 @@
 [![CI](https://github.com/deepnote/jupyterlab-deepnote/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/deepnote/jupyterlab-deepnote/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/deepnote/jupyterlab-deepnote/graph/badge.svg?token=OV32VZNOJ2)](https://codecov.io/gh/deepnote/jupyterlab-deepnote)
 
-A Deepnote extension for JupyterLab
-
-This extension is composed of a Python package named `jupyterlab_deepnote`
-for the server extension and a NPM package named `jupyterlab-deepnote`
-for the frontend extension.
+Read‑only viewer for Deepnote `.deepnote` files inside JupyterLab.
 
 ## Requirements
 
-- JupyterLab >= 4.0.0
+- Python 3.7 or higher
+- JupyterLab 4.0.0 or higher
 
 ## Install
 
-To install the extension:
+Install the extension using pip:
 
 ```bash
 pip install jupyterlab_deepnote
 ```
 
-## Uninstall
+## Usage
 
-To remove the extension, execute:
+After installation you can:
 
-```bash
-pip uninstall jupyterlab_deepnote
-```
+- Open Deepnote files (`.deepnote`) containing Deepnote projects in JupyterLab
+- Switch between notebooks inside a `.deepnote` file
+- View content in **read‑only** mode (no editing or saving back to the `.deepnote` file)
 
-## Troubleshoot
+## Compatibility and Maintenance
 
-If you are seeing the frontend extension, but it is not working, check
-that the server extension is enabled:
+This extension is maintained to be compatible with JupyterLab versions 4.x. It is recommended to keep your JupyterLab installation updated within this major version to ensure full compatibility.
+
+## 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 list
 ```
 
-If the server extension is installed and enabled, but you are not seeing
-the frontend extension, check the frontend extension is installed:
+Check frontend extensions:
 
 ```bash
 jupyter labextension list
 ```
+
+## Uninstall
+
+To remove the extension, run:
+
+```bash
+pip uninstall jupyterlab_deepnote
+```
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project.

RELEASE.md

@@ -1,6 +1,6 @@
 # Making a new release of jupyterlab_deepnote
 
-The extension can be published to `PyPI` and `npm` manually or using the [Jupyter Releaser](https://github.com/jupyter-server/jupyter_releaser).
+This extension requires both a frontend and backend component to function properly. Therefore, we only publish the Python package to `PyPI`. The NPM package alone would not do anything and is not published separately.
 
 ## Manual release
 
@@ -49,12 +49,7 @@ twine upload dist/*
 
 ### NPM package
 
-To publish the frontend part of the extension as a NPM package, do:
-
-```bash
-npm login
-npm publish --access public
-```
+The frontend part of this extension is not published separately as an NPM package because it requires the backend component to function. Publishing only the NPM package would not provide a working extension.
 
 ## Automated releases with the Jupyter Releaser