You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[#116](https://github.com/marklogic-community/mlxprs/issues/116) Updated dependencies and fixed all known security vulnerabilities
4
+
-[#119](https://github.com/marklogic-community/mlxprs/issues/119) Added SJS binding to JavaScript language
5
+
-[#97](https://github.com/marklogic-community/mlxprs/issues/97) Added a configuration option for the MarkLogic Manage app server port (used for the SJS debug server port)
6
+
-[#117](https://github.com/marklogic-community/mlxprs/issues/117) Fixed a bug with the first attempt to eval a JavaScript tab
7
+
-[#109](https://github.com/marklogic-community/mlxprs/issues/109) Prevent the database param from being used in REST calls when the database setting is empty
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+139-7Lines changed: 139 additions & 7 deletions
Original file line number
Diff line number
Diff line change
@@ -6,13 +6,13 @@ _This project and its code and functionality are not representative of MarkLogic
6
6
7
7
## Found a bug or issue?
8
8
9
-
If you find a problem, or want to request something that’s lacking, please [file an issue](https://github.com/mikrovvelle/mlxprs/issues/new). Make sure to specify which version of the extension you’re using as well as the version of MarkLogic you’re working against.
9
+
If you find a problem, or want to request something that’s lacking, please [file an issue](https://github.com/marklogic-community/mlxprs/issues/new). Make sure to specify which version of the extension you’re using as well as the version of MarkLogic you’re working against.
10
10
11
11
Even better, you can submit a Pull Request with a fix for the issue you filed.
12
12
13
13
If you would like to implement a new feature, please create a new issue with your proposal.
14
14
15
-
###Submitting an Issue
15
+
## Submitting an Issue
16
16
17
17
Please check the issue tracker before you submit an issue search, to help avoid duplicates. If your issue appears to be a bug, and hasn't been reported, open a new issue.
18
18
@@ -25,21 +25,153 @@ The following information is most helpful:
25
25
***Pointers** — If you have a hunch or just don't want to bother with a pull request,
26
26
please point me in the right direction (e.g. line numbers) to fix it.
27
27
28
-
### Submitting a Pull Request
28
+
# Development
29
+
30
+
## Project Layout
31
+
32
+
***package.json** — Metadata about the project, including details for the extensions browser, dependencies, build scripts, commands and user configuration
33
+
***client** — Main extension folder
34
+
***extension.ts** — Code insertion point. Contains initialization code and defines commands callable by user.
35
+
***marklogicClient.ts** — Interface to MarkLogic [Node Client API](https://github.com/marklogic/node-client-api) package, which is used to communicate with ML Server.
36
+
***marklogic-types.d.ts** — TypeScript type declarations used by the package.
37
+
***server** — Language server extension folder (provides syntax highlighting; based on vscode-languageserver extension)
38
+
***package.json** — As the language server is technically a separate package, this defines the dependencies for it
39
+
***server.ts** — Code insertion point. Contains initialization code for language server.
40
+
41
+
* Another important file is .vscode/settings.json. It is recommended that you use settings.json.template to create settings.json, and then customize settings.json to your local environment. Alternatively, these values can also be changed within VSCode when you change settings for this specific workspace.
42
+
43
+
## Building The Project
44
+
45
+
It is recommended to use VSCode as the editor for this package, as it can self-load a debug instance.
46
+
47
+
* Open the project folder in VSCode
48
+
* Select the "Run and Debug" sidebar window (Ctrl+Shift+D)
49
+
* Choose "Launch Extension (debug)" from the RUN AND DEBUG dropdown menu
50
+
* Press the green play button or F5 to compile and launch the plugin in a test environment
51
+
* Please see the README.md file for information on configuring and working in the test environment
52
+
53
+
Building the project requires [Node.js](https://nodejs.org/) to be installed on your local machine. Node v14 LTS is recommended.
54
+
55
+
First, dev dependencies must be installed. Run `npm install` in both this folder, and in the `./server` folder. For example:
56
+
57
+
```
58
+
npm install
59
+
cd server
60
+
npm install
61
+
cd ..
62
+
```
63
+
A shorthand script that does all of that for you is
64
+
```
65
+
npm run npmInstallClientAndServer
66
+
```
67
+
68
+
## Testing
69
+
70
+
The project contains three test applications.
71
+
72
+
* Client Tests - Runs the test files under /client/test/suite, transpiled to /dist/test/suite
73
+
* client.test.js
74
+
* xqyRuntime.test.js
75
+
* Server Tests - Runs the test files under /server/test/suite, transpiled to /server/dist/test/suite
76
+
* server.test.js
77
+
* Client-Integration Tests - Runs the test files under /client/test/integration, transpiled to /dist/test/integration
78
+
* Requires ML App Server setup first (See "Integration Testing Setup" below for more information)
79
+
* sjsAdapter.test.js
80
+
81
+
82
+
### Integration Testing Setup
83
+
84
+
JavaScript debugger integration testing requires a running MarkLogic server where you have full admin rights. Ideally, you should use a dedicated MarkLogic instance for this purpose. The tests assume the existence of a "mlxprs-test" application server running on port 8055 using the "mlxprs-test-content" and "mlxprs-test-modules" databases. Those values are set in gradle.properties and the admin password should be set in gradle-local.properties. Then you can use the command, "./gradlew -i mlDeploy" to build and configure the databases and application servers.
85
+
86
+
### Integration Test Overview
87
+
The integration test will do the following:
88
+
* Upload test scripts and modules to `Modules` database
89
+
* Run tests against the uploaded scripts and MarkLogic application server, simulating JS debugger interactions
90
+
* Delete scripts from `Modules` databse
91
+
* Results are currently written to "results/integrationTestResults.xml".
92
+
93
+
### Testing from within VSCode
94
+
Within VSCode, unit tests are available from the dropdown menu in the Run and Debug panel. There are currently three run configurations for three test sets in launch.json
95
+
96
+
* "Launch Client Tests"
97
+
* "Launch Server Tests"
98
+
* "Launch Client-Integration Tests"
99
+
100
+
101
+
For the Client-Integration test, the code (test code only) defaults to the same settings as the default values in the gradle.properties file. If you need to override the default properties, you have 3 options.
102
+
1. Edit the values the integration.env file (in ${workspaceFolder}/client/test/integration), and add the following property to the launch configuration for Client-Integration:
2. Export environment variables with the same names as the examples in integration.env. For example in a bash shell:
107
+
```
108
+
export ML_PASSWORD=admin
109
+
```
110
+
3. If you are running the tests from within VSCode, you can package and load the MarkLogic extension, and set the values on the extension settings page. If you need to build the artifact so that you can load the version of the extension you are working on, please see the "Building the artifact" section below.
111
+
112
+
Note that the order of priority for setting the property values in the test code is the following
113
+
1. Environment variables
114
+
2. Extension settings
115
+
3. Default values (hard-coded, but matches gradle.properties)
116
+
117
+
118
+
### Testing from the command line
119
+
Run these two npm scripts from the command line in the root directory of the project to execute the tests. Note that VSCode must not be running while you run the tests.
<mark>The final test (the integration tests), should not be run while VSCode is open.</mark>
127
+
128
+
To ensure a clean build, you may also run this npm script before running the npmInstallClientAndServer script.
129
+
```
130
+
npm run completeClean
131
+
```
132
+
133
+
## Building the artifact
134
+
135
+
- Install the vsce tool
136
+
```
137
+
npm install -g @vscode/vsce
138
+
```
139
+
- Build the artifact
140
+
```
141
+
vsce package
142
+
```
143
+
- If you are running in a Windows environment, you will need to use npx:
144
+
```
145
+
npx vsce package
146
+
```
147
+
This should produce a file with the name, "mlxprs-<version>.vsix"
148
+
149
+
### Windows environment - IMPORTANT NOTE
150
+
The same NPM scripts should work in Windows, however this is not thoroughly verified. In order to run all the scripts from package.json in a Windows environment, it is recommended that you install the 'rimraf', 'typescript', and 'webpack' node packages globally.
151
+
```
152
+
npm install -g rimraf
153
+
npm install -g typescript
154
+
npm install -g webpack
155
+
```
156
+
157
+
## Submitting a Pull Request
29
158
30
159
Please refer to [Github's documentation on the matter](https://help.github.com/articles/creating-a-pull-request/).
31
160
32
-
####Formatting code
161
+
## Formatting code
33
162
34
163
Project coding standards for formatting and styling are documented in `.editorconfig` and `.eslintrc.json`. Both of these tools offer VS Code extensions to automatically recommend and/or apply rules while editing:
35
164
36
165
-[editorconfig VS Code extension](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig)
0 commit comments