diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..88e4d1fc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,85 @@ +# Contributing to Deephaven in VS Code + +## Installation from .VSIX + +This extension can also be installed directly from a `.vsix`. To get a `.vsix`, you can either: + +Download one from the [releases/](releases/) folder. + +or + +Build a .vsix locally via `npm run package` + +Then install in vscode: +![Install Deephaven in VS Code](docs/install.png) + +## Publishing + +### Configuration + +Publishing a vscode extension requires: + +- Azure AD organization - https://dev.azure.com/deephaven-oss/ +- Marketplace publisher - https://marketplace.visualstudio.com/publishers/deephaven +- Personal access token - associated with a user in the Azure AD organization + > NOTE: This can be set in `VSCE_PAT` env variable + +### Versioning Strategy + +We are following the official `vscode` extension publishing guidance. + +- Pre-release versions use `major.ODD_NUMBER.patch` version scheme (e.g. `1.1.3`) +- Release versions use `major.EVEN_NUMBER.patch` versions scheme (e.g. `1.2.3`) + +> Note that `vscode` will always install a later release version instead of pre-release, so it's important to always have a pre-release version that is later than the release version if we want to allow pre-release users to stay on the latest pre-release. + +You can find additional details here: +https://code.visualstudio.com/api/working-with-extensions/publishing-extension#prerelease-extensions + +### Publish a new Version + +1. Set `VSCE_PAT` env variable to personal access token for a user in the https://dev.azure.com/deephaven-oss/ org. +1. Increment the version number in `package.json` + > See [versioning strategy](#versioning-strategy) for details on our version number scheme. +1. Use `vsce` cli to publish + + ```sh + # Pre-release + vsce publish --pre-release + ``` + + ```sh + # Release + vsce publish + ``` + +## PNG Generation + +Logo .pngs were generated from .svgs using `rsvg-convert` + +``` +rsvg-convert -w 128 -h 128 images/dh-community-on-dark-128.svg -o images/dh-community-on-dark-128.png +rsvg-convert -w 128 -h 128 images/dh-community-on-light-128.svg -o images/dh-community-on-light-128.png +``` + +## Implementation Notes + +### Server Connection + +### DHC + +The first time a connection is made to a `DHC` server, the extension will: + +1. Download the JS API from the server +2. Check server auth config. If anonymous, connect anonymously. If `PSK` prompt for `PSK`. + +If auth succeeds and connection was initiated by running a script: + +1. Run the script against the server +2. Update panels in vscode and deephaven. + +On subsequent script runs, the session will be re-used and only steps 4 and 5 will run + +### Downloading JS API + +The extension dynamically downloads and loads the DH JS API from a running DH Core server. At runtime, `dh-internal.js` and `dh-core.js` are downloaded from the running DH server (default http://localhost:10000). The files are saved to `out/util/tmp` as `.cjs` modules, and import / export are converted to cjs compatible ones. For implementation details, see [src/dh/dhc.ts#getDhc](https://github.com/deephaven/vscode-deephaven/blob/main/src/dh/dhc.ts#L62). diff --git a/README.md b/README.md index 0f3ee48b..d7b8e5b3 100644 --- a/README.md +++ b/README.md @@ -6,23 +6,11 @@ Deephaven in VS Code - Run all - Run selected code - View output in vscode panels -- View output in DH panels (depends on [pr#1925](https://github.com/deephaven/web-client-ui/pull/1925) to automatically update panels) ![Deephaven in VS Code Extension](docs/extension.png) ## Installation -This extension is not yet published to the marketplace, but you can install a `.vsix` directly. To get a `.vsix`, you can either: - -Download one from the [releases/](releases/) folder. - -or - -Build a .vsix locally via `npm run package` - -Then install in vscode: -![Install Deephaven in VS Code](docs/install.png) - > Note: There are some `vscode` bugs that cause some flakiness with the `run` button. vscode `v90` introduced an optional `workbench.editor.alwaysShowEditorActions` setting. Setting this to `true` improves the experience here. Namely the run button will not disappear when running commands or selecting its dropdown. See https://github.com/deephaven/vscode-deephaven/issues/1 for more details. ## Connecting to a Server @@ -61,7 +49,7 @@ Scripts will be run against the active connection or default to the first connec ![Deephaven: Run](docs/run.png) -Note that `vscode` will remember your selection so you can just click the `run` button (play icon) the next time. +> Note that `vscode` should remember your selection so you can just click the `run` button (play icon) the next time; however, we have observed cases where this does not always work. ### Run a selection @@ -70,35 +58,10 @@ Note that `vscode` will remember your selection so you can just click the `run` ![Deephaven: Run Selection](docs/run-selection.png) -Note that `vscode` will remember your selection so you can just click the `run` button (play icon) the next time. +> Note that `vscode` should remember your selection so you can just click the `run` button (play icon) the next time; however, we have observed cases where this does not always work. ## Code Snippets The `vscode-deephaven` extension comes with some predefined `python` snippets. These insert pre-defined code snippets into an editor. To use, simply type `ui` to see available snippets. ![Code Snippets](docs/code-snippets.png) - -## Implementation Notes - -### Server Connection - -### DHC - -The first time a connection is made to a `DHC` server, the extension will: - -1. Download the JS API from the server -2. Check server auth config. If anonymous, connect anonymously. If `PSK` prompt for `PSK`. - -If auth succeeds and connection was initiated by running a script: - -1. Run the script against the server -2. Update panels in vscode and deephaven. - -On subsequent script runs, the session will be re-used and only steps 4 and 5 will run - -### Downloading JS API - -The extension dynamically downloads and loads the DH JS API from a DH Core server. - -- `src/jsApi.downloadDhFromServer()` - At runtime, `dh-internal.js` and `dh-core.js` are downloaded from the running DH server (default http://localhost:10000). The files are saved to `out/tmp` as `.cjs` modules, and import / export are converted to cjs compatible ones. diff --git a/images/dh-community-on-dark-128.png b/images/dh-community-on-dark-128.png new file mode 100644 index 00000000..73f1bd63 Binary files /dev/null and b/images/dh-community-on-dark-128.png differ diff --git a/images/dh-community-on-dark-128.svg b/images/dh-community-on-dark-128.svg new file mode 100644 index 00000000..db591729 --- /dev/null +++ b/images/dh-community-on-dark-128.svg @@ -0,0 +1,14 @@ + + + + + + + \ No newline at end of file diff --git a/images/dh-community-on-light-128.png b/images/dh-community-on-light-128.png new file mode 100644 index 00000000..6375e42a Binary files /dev/null and b/images/dh-community-on-light-128.png differ diff --git a/images/dh-community-on-light-128.svg b/images/dh-community-on-light-128.svg new file mode 100644 index 00000000..49a9c62c --- /dev/null +++ b/images/dh-community-on-light-128.svg @@ -0,0 +1,13 @@ + + + + + + \ No newline at end of file diff --git a/package.json b/package.json index 32eb71b4..0a317d55 100644 --- a/package.json +++ b/package.json @@ -1,13 +1,18 @@ { "name": "vscode-deephaven", + "version": "0.1.2", "displayName": "Deephaven in VS Code", "description": "", - "publisher": "Deephaven Data Labs", + "publisher": "deephaven", + "icon": "images/dh-community-on-dark-128.png", + "galleryBanner": { + "color": "#040427", + "theme": "dark" + }, "repository": { "type": "git", "url": "https://github.com/deephaven/vscode-deephaven" }, - "version": "0.0.2", "engines": { "vscode": "^1.87.0" },