add contributing docs (jupyter-server#225)

* add contributing docs

* add some local/remote docs

MANIFEST.in

@@ -22,6 +22,7 @@ graft data_studio_jupyter_extensions/labextension
 recursive-include data_studio_jupyter_extensions *.html
 recursive-include data_studio_jupyter_extensions *.png
 recursive-include data_studio_jupyter_extensions *.yaml
+recursive-include docs *.md
 
 # Javascript files
 graft src

README.md

@@ -123,7 +123,7 @@ tbump --only-patch <version>
 First, build the docker container:
 
 ```
-make build
+make build-docker
 ```
 
 The Docker image comes with multiple modes.

docs/contributing.md

@@ -0,0 +1,142 @@
+# Contributing
+
+This page gives a concise overview of the package. As your contribute to this project, please make sure your contributions follow this guide or update it when necessary.
+
+- [Development principles](#Development-principles)
+- [Overview of the repository](#Overview-of-the-repository)
+- [Installing development workflow](#Installing-development-workflow)
+- [Running tests](#Running-tests)
+- [Releasing a new version](#Releasing-a-new-version)
+
+## Development principles
+
+1. **Always extend.** Jupyter Server and JupyterLab offer extension points for customization. If you can avoid it, never fork open-source Jupyter libraries. If you find a need to fork, please consider contributing this change back to the open-source (Jupyter is an OSRB approved project).
+2. **Test thoroughly.** The CI pipelines will fail if the test coverage falls below 80%. Strive for full test coverage wherever possible or have good reasons to skip.
+3. **Keep things simple.** Write clear and concise code. Name extensions, modules, and classes clearly. Keep the project organized. Strive for long-term sustainability.
+
+## Overview of the repository
+
+This repository compiles a set of extensions/plugins for Apple's Data Studio (DS) JupyterLab platform.
+
+### Server (Python) extensions
+
+The `data_studio_jupyter_extensions/` directory holds all the Python backend/server extensions.
+
+- `auth/`: DS's login handler and auth manager.
+- `configurables/`: DS's custom, `Configurable` objects, e.g. a session manager, kernel_manager, provisioner, etc.
+- `extensions/`: a set of Jupyter server extensions made specifically for Data Studio.
+- `kernel_resources`: images for kernel specs.
+- `modes/`: Jupyter configuration files that configure DS JupyterLab depending on where it's running.
+
+For information on how to extension the Jupyter Server, see the [Jupyter Server Extensions docs](https://jupyter-server.readthedocs.io/en/latest/developers/extensions.html).
+
+### Frontend (TypeScript) extensions
+
+The `src/` directory holds all of the frontend JupyterLab plugins. For information on how to extend JupyterLab, see the JupyterLab ["Extension Developer Guide"](https://jupyterlab.readthedocs.io/en/stable/extension/extension_dev.html#extension-developer-guide).
+
+For convenience, this package comes with `MakeFile` commands to build a JupyterLab extension.
+
+```
+make build.
+```
+
+### Deployment
+
+The `deployment/` directory contains the DockerFile, scripts, and configuration for publishing a Docker image. The Docker image is published automatically by CI when the version of the package is updated (see the [Releasing a new version](#Releasing-a-new-version) section below)
+
+## Installing development workflow
+
+The package comes with a `Makefile` command to simplify development installation.
+
+To install the development version, run `make install-dev`
+
+## Running tests
+
+The package comes with a `Makefile` command to simplify running tests.
+
+To run all tests, run `make test`
+
+To manually setup the tests, install using:
+
+```
+pip install -q ".[test]" --index-url https://pypi.apple.com/simple
+```
+
+Run the Python tests using pytest:
+
+```
+pytest --cov=data_studio_jupyter_extensions
+```
+
+Run the Javascript tests:
+
+```
+yarn test:cov
+```
+
+## Releasing a new version
+
+To cut a release, use `tbump`. This will automatically change the version number in multiple places across the repository and enforce that everything stays in sync. **DO NOT** manually change the version number.
+
+Steps to using tbump:
+
+1. Create a branch
+2. Push that branch to your fork on Github, making sure to set upstream appropriately, e.g. `git push -u origin my-branch`.
+3. Run tbump, e.g.:
+
+   ```
+   > tbump --only-patch 0.14.5
+
+   :: Bumping from 0.14.4 to 0.14.5
+   => Would update current version in pyproject.toml
+   => Would patch these files
+   - data_studio_jupyter_extensions/_version.py:1 __version__ = "0.14.4"  # pragma: no cover
+   + data_studio_jupyter_extensions/_version.py:1 __version__ = "0.14.5"  # pragma: no cover
+   - src/status.tsx:33 const VERSION = '0.14.4';
+   + src/status.tsx:33 const VERSION = '0.14.5';
+   - version:1 0.14.4
+   + version:1 0.14.5
+   => Would run these git commands
+   $ git add --update
+   $ git commit --message Bump to 0.14.5
+   $ git tag --annotate --message v0.14.5 v0.14.5
+   $ git push --atomic origin x v0.14.5
+   :: Looking good? (y/N)
+   > y
+   => Updating current version
+   * Set current version to 0.14.5 in pyproject.toml
+   => Patching files
+   - data_studio_jupyter_extensions/_version.py:1 __version__ = "0.14.4"  # pragma: no cover
+   + data_studio_jupyter_extensions/_version.py:1 __version__ = "0.14.5"  # pragma: no cover
+   - src/status.tsx:33 const VERSION = '0.14.4';
+   + src/status.tsx:33 const VERSION = '0.14.5';
+   - version:1 0.14.4
+   + version:1 0.14.5
+   => Performing git operations
+   $ git add --update
+   $ git commit --message Bump to 0.14.5
+   $ git tag --annotate --message v0.14.5 v0.14.5
+   $ git push --atomic origin x v0.14.5
+   Reorder python imports...................................................Passed
+   black....................................................................Passed
+   prettier.................................................................Passed
+   flake8...................................................................Passed
+   Fix End of Files.........................................................Passed
+   Check for case conflicts.................................................Passed
+   Check that executables have shebangs.................(no files to check)Skipped
+   Fix requirements.txt.................................(no files to check)Skipped
+   eslint...............................................(no files to check)Skipped
+   pylint...................................................................Passed
+   [x 0eb47da] Bump to 0.14.5
+   4 files changed, 4 insertions(+), 4 deletions(-)
+   Enumerating objects: 16, done.
+   Counting objects: 100% (16/16), done.
+   Delta compression using up to 16 threads
+   Compressing objects: 100% (7/7), done.
+   Writing objects: 100% (9/9), 736 bytes | 368.00 KiB/s, done.
+   Total 9 (delta 5), reused 0 (delta 0), pack-reused 0
+   remote: Resolving deltas: 100% (5/5), completed with 5 local objects.
+   To https://github.pie.apple.com/zsailer/data_studio_jupyter_extensions.git
+   a27562a..0eb47da  x -> x
+   * [new tag]         v0.14.5 -> v0.14.5
+   ```

docs/local-cluster.md

@@ -0,0 +1,29 @@
+# Connecting local JupyterLab to remote Kernels
+
+After installing the `data_studio_jupyter_extension` package, JupyterLab Data Studio can be run against a remote Notebook Service using by simply switching the mode:
+
+```
+jupyter datastudio --mode local-remote
+```
+
+When running the application against a remote Notebook Service, JupyterLab Data Studio expects the following variables in the current environment:
+
+```
+DATASTUDIO_PROJECT_ID=... # Get from Data Studio Projects page
+DATASTUDIO_NOTEBOOK_ID=... # Get from Data Studio Notebook Servers page.
+DATASTUDIO_UI_URL=https://ds-int.apple.com/ # Data Studio's UI page.
+DATASTUDIO_API_URL=https://notebook-service-dev.us-east-1a.app.apple.com/api/v1 # Data Studio's API URL
+DS_NAMESPACE=spark-data-studio-test-us-west-3a-dev1 # Get from Kubenetes cluster. Namespace where kernels are running.
+ISSUER=https://iam.corp.apple.com
+KEY_URL=https://iam.corp.apple.com/oauth2/v3/certs
+AUDIENCE=notebook-server-int
+CLIENT_ID=d314ef93-a7b3-4451-b68d-51bd395ba7f2
+HBPORT=18525
+SHELLPORT=27965
+IOPUBPORT=6232
+STDINPORT=10270
+CONTROLPORT=25232
+API_TOKEN=... # Get from Data Studio page. This is the cookie value for "datastudio-session-token`.
+IAS_CLIENT_SECRET=... # [SECRET] Get from Data Studio UI Team.
+IAS_CLIENT_ID=... # [SECRET] Get from Data Studio UI Team
+```

docs/running-locally.md

@@ -0,0 +1,25 @@
+# Running a local Data Studio JupyterLab
+
+When developing Jupyter extensions for DS, it's often useful to run DS JupyterLab entirely locallu, rather than running in an INT environment. The [Notebook Service Gateway](https://github.pie.apple.com/pie-data-studio/notebook_service_gateway) project makes this possible by mocking the DS Notebook Service. To run in local mode, follow the steps below.
+
+Install `notebook_service_gateway`, a local service that mocks Data Studio's notebook service.
+
+```
+git clone [email protected]:pie-data-studio/notebook_service_gateway.git
+cd notebook_service_gateway
+make install
+```
+
+Run the Notebook Service Gateway:
+
+```
+> jupyter notebook-service
+```
+
+In a second terminal, run Data Studio Jupyter in `local-local` mode:
+
+```
+jupyter datastudio --mode=local-local
+```
+
+This runs a local Data Studio JupyterLab instance pointing at the Notebook Service Gateway started in the first terminal. Together, they mimic a deployed DS JupyterLab.