Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
190 lines (107 loc) · 7.31 KB

CONTRIBUTING.md

File metadata and controls

190 lines (107 loc) · 7.31 KB

Contributing

This contains information about how to get set up for development with the tools!

For questions, issues, or concerns you can reach out to Zach Norman at zacharyanorman@gmail.com or zachary.norman@nv5.com.

If you are a developer and new to NX, see NX.md

If you are using ubuntu on windows, replace commands with npx nx instead of just nx.

With the update to NX 16, there are a fex outstanding NX bugs that need to be resolved for everything to work quite as expected.

Some projects may require to be developed a little differently with "nx build my-app --watch" and "node dist/apps/my-app/main.js" to execute.

Node and NPM Versions

This repository is forward leaning with LTS and new versions of node and NPM.

At the time of writing this, you need:

  • Node.js 20.12 or newer
  • NPM 9.2 or 10.0 or newer

You should see an error when you try to install dependencies or package the extension, both of which check your node and NPM versions to make sure they are valid.

You can also view these at anytime with the "engines" tag in the package.json file.

Quick Start: Building Pre-release Extensions

To build your own version of the extension run the following from the root of this repository:

  1. npm i -g nx vsce

  2. npm i

  3. npm run package

  4. Manually install the generated idl-*.vsix file in VS Code

Quick Links and Helpful Information

Developer docs (tests, architecture, etc.) are located in: extension/docs/developer

Setup

This repository uses NX to manage apps and libraries. NX is a great tool for monorepo code management and offers great functionality to make your life easier when developing.

New to NX? Check out their website https://nx.dev/ or one of their tutorials https://nx.dev/angular-tutorial/01-create-application.

  1. Make sure nx is installed globally. Use npm i -g nx.

  2. From the main folder, run npm i in install all dependencies.

  3. Additionally, you should install the recommended extensions for this repository which includes Prettier and ESLint to make sure code is properly formatted and consistent.

This is a firm requirement so all code has the same style and appearance between developers.

  1. Before major changes, execute npm run code-prep which will automatically lint, format, and alert you of any issues.

Development

  1. You can easily develop all components of the application using:
npm start

This will build, and rebuild on changes, the client, server, and parsing-worker to support the language server. When any changes are made, the bundles will be re-built automatically.

  1. Press "F5" to launch the extension development environment

  2. On changes, and after a few seconds, things will rebuild and you can refresh using the debug menu in VSCode.

Updating the ENVI and IDL MCP Tools

  1. Create a file at the root level of this workspace called build.json

  2. Populate the contents with the following:

{
  "mcp-dir": "C:\\path-to-envi-idl-mcp-tools",
  "idl-dir": "C:\\Program Files\\NV5\\ENVI62\\IDL92\\bin\\bin.x86_64"
}
  1. Execute npm run build-mcp-tools

NOTE: This is a manually step because the SAVE files are bundled in the extension. Anytime we recompile IDL code, it is tracked as changes for git, so that's why this doesn't happen every time

Changing Extension Contribution

An added complexity with the recent changes is that the contribution points for this extension are stored in code and added to the package.json file before packaging or during development.

See the source code in apps/package-json/src/main.ts and apps/package-json/src/contributes for the code that changes our contribution points.

The main reason for this is so that, using code, we can verify that our translation and auxiliary files are where we expect them to be. We can also automatically create the translation strings so we don't need to do that by hand which is a burden.

To update the package.json file, after making code changes, you can execute npm run build-package-json.

Packaging Extension

In order to package the IDL extension, execute the following NPM script:

npm run package

Internationalization Development

When you update the internationalization files, execute:

npm run build-i18n

Note: The translations are stored in libs/translation/src/lib/languages

They are based in code so that we have strict checking and types to make sure all languages have the same content

Developing the Web View

Similar to the client and language server, here's the command to execute for development of the web view:

nx build idl-webview --watch

It is probably easiest to have a separate terminal running with this active in addition to the client and server.

This will take 5-10 seconds to update the dist folder after changes have been made and, if you have the server

Testing

For more details on testing, see the TESTING_* files in extension/docs/developer folder.

At a high level, testing happens in two places:

  1. Libraries to make sure functionality works as expected

  2. Integration to make sure all components come together and work as expected.

Most of our testing happens in the first step above as the second is more complicated at this point in time.

To test this application you can run npm run test-everything which will run all tests and take several minutes to run. To do this, you need to have ENVI and IDL installed.

If you are just updating or working with the libraries, you can use npm run test-libs which will just test the libraries. This does not require ENVI and IDL to be installed to run.

Writing Integration Tests

Integration tests live in this folder apps\client-e2e\src\tests

They are separated by test runners, which are where tests are registered for each component of the extension. These test runners are the files prefixed with _ at in each sub folder.

To write new integration tests, here's the best process:

  1. Identify the relevant sub-folder to add your tests to

  2. For test development, we recommend commenting out the test runners that aren't related to what you are running. you can find that in apps\client-e2e\src\tests\test-runner.ts

  3. Create a new test - it's recommended to copy/paste from an exaisting test and adjust to meet your needs

If you have additional files needed for the test, the standard location to save content is here idl\test\client-e2e

  1. In the relevant test runner, you should register the test. Open one of the relevant test runners to see an example of this.

Note: You can limit different tests to skip OS/CPU combinations or be limited to specific versions. You can see examples of this in apps\client-e2e\src\tests\mcp\_mcp-test-runner.ts

Releasing

  1. Bump the version of the extension in libs\shared\extension\src\lib\version.interface.ts to match thenew version

  2. Execute npm run package

  3. Commit changes from version to Github

  4. Merge the develop branch into main

  5. Wait for GitHub actions to finish to make sure that docs build

  6. Create release checkpoint on GitHub and attach the VSIX file to release

  7. Publish release to the marketplace with vsce publish (you need special permissions to do this)

  8. Wait and check for confirmation email that the extension was published!