-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #177 from KxSystems/KXI-27841
KXI-27841 Repo cleanup, adding contribution guides
- Loading branch information
Showing
11 changed files
with
322 additions
and
74 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| # Contributing to kdb VS Code Extension | ||
|
|
||
| Your input is very welcome, some examples of this include: | ||
|
|
||
| - Reporting a bug | ||
| - Submitting a fix | ||
| - Proposing new features | ||
|
|
||
| ## Reporting a bug | ||
|
|
||
| Bugs can be reported via [Issues](https://github.com/KxSystems/kx-vscode/issues) | ||
|
|
||
| Where possible include: | ||
|
|
||
| - Quick summary and/or background | ||
| - Steps to reproduce | ||
| - Be specific | ||
| - Provide sample code if you can | ||
| - What you expected would happen | ||
| - What actually happens | ||
| - Other relevant notes | ||
|
|
||
| ## Submitting a fix | ||
|
|
||
| Fixes can be submitted via a pull request: | ||
|
|
||
| 1. Fork the repo and create your branch from `dev` | ||
| 2. If you've added code that should be tested, add tests | ||
| 3. Ensure the test suite passes, using `npm run test` | ||
| 4. Apply the prettier formatting, using a plugin or manually using `npm run format` | ||
| 5. Create a pull request for your branch | ||
|
|
||
| ### License | ||
|
|
||
| When you submit code changes your submissions are understood to be under the same [Apache 2.0](https://github.com/KxSystems/kx-vscode/blob/main/LICENSE) that covers the project. Please feel free to contact the maintainers if that's a concern. | ||
|
|
||
| ## Proposing a new feature | ||
|
|
||
| Please use [email protected] to raise any questions, feature requests or feedback. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| name: Bug Report | ||
| description: File a bug report | ||
| title: "[Bug]: " | ||
| labels: ["bug", "triage"] | ||
| projects: ["KxSystems/kx-vscode"] | ||
| body: | ||
| - type: markdown | ||
| attributes: | ||
| value: | | ||
| Thanks for taking the time to complete this bug report | ||
| - type: input | ||
| id: contact | ||
| attributes: | ||
| label: Contact Details | ||
| description: How can we get in touch with you if we need more info? | ||
| placeholder: ex. [email protected] | ||
| validations: | ||
| required: false | ||
| - type: textarea | ||
| id: what-happened | ||
| attributes: | ||
| label: What happened? | ||
| description: Also tell us, what did you expect to happen? | ||
| placeholder: Tell us what you see! | ||
| value: "A bug happened!" | ||
| validations: | ||
| required: true | ||
| - type: input | ||
| id: version | ||
| attributes: | ||
| label: Version | ||
| description: What version of the extension are you running? | ||
| validations: | ||
| required: true | ||
| - type: textarea | ||
| id: logs | ||
| attributes: | ||
| label: Relevant log output | ||
| description: Please copy and paste any relevant log output (e.g. contents of the 'kdb' Output pane) | ||
| render: shell |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| blank_issues_enabled: false |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| ### Changes introduced by this PR | ||
|
|
||
| - |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4,11 +4,9 @@ This is a companion extension for kdb developers to edit q files, connect to kdb | |
|
|
||
| Please use [email protected] to raise any questions, issues or feedback. | ||
|
|
||
| <!-- | ||
| [](https://github.com/KxSystems/kx-vscode/actions/workflows/ci.yml) | ||
|
|
||
| [](https://github.com/KxSystems/kx-vscode/actions/workflows/release.yml) | ||
| --> | ||
|
|
||
| ## Contents | ||
|
|
||
|
|
@@ -67,25 +65,25 @@ You can install q from the VS Code extension. You still need to register for [kd | |
|
|
||
| **Step 1**: Click `Install new instance` from the prompt if no q installation is flagged. If this prompt is cancelled, then use the aforementioned [install q](#install-q). | ||
|
|
||
|  | ||
|  | ||
|
|
||
| **Step 2**: If you have already registered for kdb+ or kdb Insights, then choose `Select/Enter a license`. If you haven't registered, choose `Acquire license`, this will open a dialog with a redirect link to register for [kdb Insights Personal Edition](https://kx.com/kdb-insights-personal-edition-license-download/). | ||
|
|
||
|  | ||
|  | ||
|
|
||
| **Step 3**: With the license secured, you can then link this to VS Code by either `pasting license string` or `selecting license file` from your PC; the latter method is recommended for new users. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| The base64 encoded license string can be found in the welcome email received after registration, under the download link for the license file. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| The `k4.lic` or `kc.lic` license file can be downloaded to your PC. | ||
|
|
||
| **Step 4**: Set a [`QHOME` environment variable](https://code.kx.com/q/learn/install/#step-5-edit-your-profile) to the location used by the kdb VS Code install. A notification dialog displays the location of q, as do the extension [settings](#settings). This will allows you to use q outside of VSCode. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| If q is installed at `C:\q`, then `QHOME` is `C:\q`. | ||
|
|
||
|
|
@@ -101,11 +99,11 @@ The kdb VS Code extension allows you to connect VS Code to a q process; this can | |
|
|
||
| **Step 2**: Within the kdb VS Code extension, click _connect to kdb server_, or *Add new connection\*\* from the *CONNECTIONS\* context menu. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| **Step 3**: When prompted to select the kdb type, choose **Enter a kdb endpoint**. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| **Step 4**: Assign a _server name / alias_. The server name selected **cannot be `local` or `insights`**, as these are reserved for use by [managed q sessions](#managed-q-session) and [kdb Insights Enterprise connections](#kdb-insights-enterprise); e.g. _dev_ | ||
|
|
||
|
|
@@ -117,11 +115,11 @@ The kdb VS Code extension allows you to connect VS Code to a q process; this can | |
|
|
||
| Upon completion, the localhost connection appears under _KX:CONNECTIONS_ in the left hand panel. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| **Step 7**: Right-click the connection to _connect kdb server_. Ensure the q process is running. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| If authentication is required to access the connection, from the connection dropdown menu, add the required _username_ and the _password_, clicking Enter to move between the two. | ||
|
|
||
|
|
@@ -135,11 +133,11 @@ This runs a q session using the existing kdb installed as part of the kdb VS Cod | |
|
|
||
| **Step 1**: Click _connect to kdb server_ or _Add new connection_ from the _CONNECTIONS_ context menu. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| **Step 2**: When prompted to select the kdb type, choose **Enter a kdb endpoint**. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| **Step 3**: Set the _server name / alias_ to `local`. | ||
|
|
||
|
|
@@ -151,7 +149,7 @@ This runs a q session using the existing kdb installed as part of the kdb VS Cod | |
|
|
||
| **Step 6**: Right-click the managed q process listed under _KX:CONNECTIONS_, and click _Start q process_. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| **Step 7**: From the same right-click menu, click _Connect kdb server_. This connects to the child q process running inside the kdb VS Code extension. | ||
|
|
||
|
|
@@ -163,27 +161,27 @@ For kdb Insights Enterprise, the kdb VS Code extension is using a shared kdb pro | |
|
|
||
| **Step 1**: Click _connect to kdb server_. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| **Step 2**: When prompted to select a kdb type, choose _Connect to kdb insights_ | ||
|
|
||
|  | ||
|  | ||
|
|
||
| **Step 3**: Create a _server name / alias_; this can be any name, aside from `local`, which is used by the [managed q session](#managed-q-session). | ||
|
|
||
| **Step 4**: Set the _hostname_. This is the remote address of your kdb Insights Enterprise deployment: e.g `https://mykdbinsights.cloudapp.azure.com` | ||
|
|
||
| **Step 5**: The kdb Insights Enterprise connection is listed under _KX:Connections_, with its own icon. Right-click the connection and _Connect to Insights_ | ||
|
|
||
|  | ||
|  | ||
|
|
||
| **Step 6**: The kdb VS Code extension runs an authentication step with the remote kdb Insights Enterprise process; sign-in to kdb Insights Enterprise. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| After a successful connection to a kdb Insights Enterprise process, a new _DATA SOURCES_ panel will become available in the kdb VS Code extension. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| Once connected to a q process, go to [execute code](#execute-code). | ||
|
|
||
|
|
@@ -201,9 +199,9 @@ A kdb language server is bundled with the kdb VS Code extension. It offers vario | |
|
|
||
| The extension provides keyword syntax highlighting, comments and linting help. | ||
|
|
||
|  | ||
|  | ||
|
|
||
|  | ||
|  | ||
|
|
||
| ### Code navigation | ||
|
|
||
|
|
@@ -217,15 +215,15 @@ While developing q scripts, the kdb VS Code extension supports: | |
|
|
||
| View references of a function both on the side view and inline with the editor | ||
|
|
||
|  | ||
|  | ||
|
|
||
|  | ||
|  | ||
|
|
||
| ### Code Completion | ||
|
|
||
| - Keyword auto complete for the q language | ||
|
|
||
|  | ||
|  | ||
|
|
||
| - Autocomplete for local and remotely connected q processes | ||
|
|
||
|
|
@@ -265,7 +263,7 @@ To create a data source: | |
| 1. Click on the created data source where the name, API and parameterization can be applied. | ||
| 1. Click Save to persist the data source to the VS Code workspace. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| To run a data source, click 'Run' and the results populate the output and kdb results windows. | ||
|
|
||
|
|
@@ -283,7 +281,7 @@ To do this: | |
|
|
||
| 1. Return to VS Code and execute q code against the data in your scratchpad. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| ## View results | ||
|
|
||
|
|
@@ -293,21 +291,21 @@ All query executions happen remotely from the kdb VS Code extension either again | |
|
|
||
| The output view displays results as they are received by the kdb VS Code extension. It includes the query executed, a timestamp and the results. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| **Note:** You can enable/disable auto-scrolling in the VS Code settings. This setting determines whether the output view scrolls to the latest results. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| **Note** You can hide or show the full details in the console output. Go to settings of the vscode, search for kdb, check the option "Hide Detailed Console Query Output" (this option is checked by default) | ||
|
|
||
|  | ||
|  | ||
|
|
||
| - A kdb results view | ||
|
|
||
| Results are displayed under the kdb results view, which shows the returned data in a table. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| ## Settings | ||
|
|
||
|
|
||
Empty file.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters