Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
130 lines (101 loc) · 5.18 KB

CONTRIBUTING.md

File metadata and controls

130 lines (101 loc) · 5.18 KB

Contributing

Getting started

pnpm install
pnpm build:app
pnpm watch
  • pnpm build:app builds the front-end app (i.e. the H5Web viewer) with Vite.
  • pnpm watch compiles the extension code with tsc in watch mode.

Once watch mode is running, press F5 to run the extension in debug mode in a new VS Code window. If this doesn't work, check that the JavaScript Debugger extension is enabled.

Whenever you change the code of the front-end app, run pnpm build:app again in a separate terminal, wait for Vite to finish building the app, and reload the VS Code window where the extension is running with Ctrl+R.

How it works

  1. When the user opens an HDF5 file, a new webview editor opens up.
  2. The webview is initialised with an HTML document that references the compiled front-end assets located in the dist directory.
  3. VS Code loads the webview, which kicks off the H5Web viewer.
  4. Once the App component is mounted, it notifies the extension that the viewer is ready using VS Code's postMessage API.
  5. The extension then sends the URI and name of the HDF5 file opened by the user to the viewer.
  6. Finally, the viewer fetches the file with the given URI as an array buffer, passes that buffer to the H5WasmBufferProvider, and renders H5Web's App component.
  7. If the file is larger than 2 GB and can't fit into a single buffer, the App component renders a fallback StandaloneViewer, which offers to the user to browse for the file from inside the webview. In doing so, the webview can make use of H5Web's H5WasmLocalFileProvider, which has no file size restriction.

Code quality

  • pnpm lint - run all linting and code formatting commands
  • pnpm lint:eslint - lint all TS and JS files with ESLint
  • pnpm lint:eslint --fix - auto-fix linting issues
  • pnpm lint:prettier - check that all files have been formatted with Prettier
  • pnpm lint:prettier --write - format all files with Prettier

Publishing

The H5Web extension is published to the Visual Studio Marketplace and to the Open VSX Registry. To be able to publish to these platforms, you must first follow the steps outlined in the respective sections below.

Before publishing, remember to update the CHANGELOG and commit/push all changes. Then, run the following command to publish the extension to the VS Code Marketplace:

pnpm pub <patch|minor|major|x.y.z>

This will build the front-end app and the extension, bump the version in package.json and publish the extension to the Marketplace.

Do not use the pnpm publish command, as this is a reserved command for publishing packages to the NPM repository.

It will take a few minutes before the new version appears in the Marketplace, and it may take a while longer before you're able to update the extension in VS Code.

Once you're able to install the new version and confirm that it works as expected, proceed with publishing the extension to the Open VSX Registry:

pnpm pub:ovsx -p <token>

Do not pass a version number this time!

Once the extension is published, push the tag created by the first pnpm pub command, and publish a new release on GitHub to advertise it.

Visual Studio Marketplace

To be allowed to publish an extension to the Visual Studio Marketplace you must have access to both the H5Web publisher account on the Marketplace and the H5Web organisation on Azure DevOps, with the same Microsoft account.

Then, you have to generate a Personal Access Token (PAT) on Azure DevOps. Then, use the vsce CLI and your PAT to add h5web to the list of known publishers on your machine:

pnpx vsce login h5web

You're now ready to publish the extension to the Visual Studio Marketplace.

Open VSX Registry

Users of VSCodium and other forks of VSCode may not be able to install extensions from the Visual Studio Marketplace. The Open VSX Registry is an alternative managed by the Eclipse Foundation.

To be allowed to publish an extension to the registry you must create an Eclipse account, link it to your Open VSX Registry account, create a personal access token, and be added as a member of the h5web namespace by an owner of that namespace.

If the h5web namespace no longer has an owner, you may claim ownership publicly.