Skip to content

Commit

Permalink
chore: Update readme and add distTag to lerna config (deephaven#1175)
Browse files Browse the repository at this point in the history 
I added `distTag` for `latest` builds from `main`, and while updating
the `README` I felt it could use some organizing. Tried to cleanup and
group things that belonged together. Also added info about the launch
config and moved it to the workspace settings in case users need to
modify the default without worrying about it being committed. I tried
adding a `.vscode/launch.json` and it is ignored now.
  • Loading branch information
@mattrunyon
mattrunyon authored Mar 24, 2023
1 parent 2ac25ae commit b0865eb
Show file tree
Hide file tree
Showing 5 changed files with 112 additions and 63 deletions.
1 change: 0 additions & 1 deletion .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@
.vscode/*
!.vscode/settings.json
!.vscode/tasks.json
!.vscode/launch.json
!.vscode/extensions.json
!.vscode/*.code-snippets
.DS_Store
Expand Down
16 changes: 0 additions & 16 deletions .vscode/launch.json
View file

This file was deleted.

23 changes: 21 additions & 2 deletions .vscode/settings.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,5 +8,24 @@
}
],
"editor.defaultFormatter": "esbenp.prettier-vscode",
"stylelint.validate": ["css", "html", "sass", "scss"]
}
"stylelint.validate": [
"css",
"html",
"sass",
"scss"
],
"launch": {
"version": "0.2.0",
"configurations": [
{
"name": "Launch Deephaven",
"request": "launch",
"type": "chrome",
"url": "http://localhost:4000",
"webRoot": "${workspaceFolder}",
"userDataDir": "${workspaceFolder}/.vscode/chrome-debug-profile"
}
],
"compounds": []
}
}
128 changes: 85 additions & 43 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,38 @@ We're using a monorepo to manage our packages, as it becomes cumbersome to manag

[![codecov](https://codecov.io/gh/deephaven/web-client-ui/branch/main/graph/badge.svg?token=RW29S9X72C)](https://codecov.io/gh/deephaven/web-client-ui)

## Development Environment
## Package Overview

We recommend using [Visual Studio Code](https://code.visualstudio.com/) and installing the [recommended workspace extensions](https://github.com/deephaven/web-client-ui/blob/main/.vscode/extensions.json) which VS Code will suggest when you open the repo or when you browse the extensions panel. There are a few [workspace settings](https://github.com/deephaven/web-client-ui/tree/main/.vscode) configured with the repo.
There are many packages located in the [packages](./packages) directory. A few of the more important ones are:

Use Chrome for debugging, install the React and Redux extensions.
- [@deephaven/code-studio](./packages/code-studio): Main web UI used with the [deephaven-core](https://github.com/deephaven/deephaven-core/) backend. This package is the main front-end application, and depends on almost all other packages in the repository. It is often the easiest way to see the effect of your changes by opening this application. Follow the instructions in the [code-studio README.md](https://github.com/deephaven/web-client-ui/blob/main/packages/code-studio/README.md) to get it started.
- [@deephaven/components](./packages/components): Component library used within the web UI.
- [@deephaven/grid](./packages/grid): High-performance grid component used to display large tables of data.
- [@deephaven/dashboard](./packages/dashboard/): Dashboards used in [@deephaven/code-studio](./packages/code-studio) for displaying and organizing panels.
- [@deephaven/golden-layout](./packages/golden-layout): Layout framework used in [@deephaven/dashboard](./packages/dashboard/).

- [React Developer Tools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi): Allows inspection/changing the props/state of react components.
- [Redux DevTools](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=en): Inspect the redux store data.
## Contributing

For details on how to contribute to this repository, please see the [contributing guidelines](./CONTRIBUTING.md).

# Development

## Getting Started

We are still using node 16.x and npm 8.x. If you are [using nvm](https://github.com/nvm-sh/nvm#installing-and-updating), there is an [.nvmrc](.nvmrc) file, so just run `nvm install` to get the latest 16.x/8.x versions (or set up your environment to [automatically switch](https://github.com/nvm-sh/nvm#deeper-shell-integration)). Otherwise, download from the [node homepage](https://nodejs.org/en/download/).
We are using node 18.x and npm 8.x. If you are [using nvm](https://github.com/nvm-sh/nvm#installing-and-updating), there is an [.nvmrc](.nvmrc) file, so just run `nvm install` to get the latest 18.x/8.x versions (or set up your environment to [automatically switch](https://github.com/nvm-sh/nvm#deeper-shell-integration)). Otherwise, download from the [node homepage](https://nodejs.org/en/download/).

In order to use the UI, you must also be running a [deephaven-core](https://github.com/deephaven/deephaven-core) server on port 10000. The server provides APIs that the web-client-ui depends upon. An easy way to get started is to launch a Deephaven container from the [quick start guide](https://deephaven.io/core/docs/tutorials/quickstart/).

## Recommended Environment

We recommend using [Visual Studio Code](https://code.visualstudio.com/) and installing the [recommended workspace extensions](https://github.com/deephaven/web-client-ui/blob/main/.vscode/extensions.json) which VS Code will suggest when you open the repo or when you browse the extensions panel. There are a few [workspace settings](https://github.com/deephaven/web-client-ui/tree/main/.vscode) configured with the repo.

We use Chrome for development with the React and Redux extensions.

### Scripts
- [React Developer Tools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi): Allows inspection/changing the props/state of react components.
- [Redux DevTools](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=en): Inspect the redux store data.

## Scripts

- `npm install` : Install all dependencies and automatically bootstrap packages. Should be run before any of the other steps.
- `npm start`: Start building all packages and watching them (when possible). Use when you're developing, and your changes will be picked up automatically.
Expand All @@ -40,19 +58,13 @@ If your DHC address is different from the default `http://localhost:10000`, edit
VITE_PROXY_URL=http://<dhc-host>:<port>
```

## Package Overview
## Debugging from VSCode

There are many packages located in the [packages](./packages) directory. A few of the more important ones are:

- [@deephaven/code-studio](./packages/code-studio): Main web UI used with the [deephaven-core](https://github.com/deephaven/deephaven-core/) backend. This package is the main front-end application, and depends on almost all other packages in the repository. It is often the easiest way to see the effect of your changes by opening this application. Follow the instructions in the [code-studio README.md](https://github.com/deephaven/web-client-ui/blob/main/packages/code-studio/README.md) to get it started.
- [@deephaven/components](./packages/components): Component library used within the web UI.
- [@deephaven/grid](./packages/grid): High-performance grid component used to display large tables of data.
- [@deephaven/dashboard](./packages/dashboard/): Dashboards used in [@deephaven/code-studio](./packages/code-studio) for displaying and organizing panels.
- [@deephaven/golden-layout](./packages/golden-layout): Layout framework used in [@deephaven/dashboard](./packages/dashboard/).
We have a pre-defined launch config that lets you set breakpoints directly in VSCode for debugging browser code. The `Launch Deephaven` config will launch a new Chrome window that stores its data in your repo workspace. With this setup, you only need to install the React and Redux devtool extensions once. They will persist to future launches using the launch config.

## Contributing
If you are not using Chrome (e.g. Chromium on Linux), then you add a new configuration to VSCode and copy the launch config from [`settings.json`](./.vscode/settings.json). Then add the `runtimeExecutable` prop to point to your browser executable. VSCode unfortnuately does not merge workspace `settings.launch` with workspace `launch.json`, so if we add more launch configs you would need to copy to your `.vscode/launch.json` file to get the configs.

For details on how to contribute to this repository, please see the [contributing guidelines](https://github.com/deephaven/web-client-ui/blob/main/CONTRIBUTING.md).
We prefer launching a new window instead of attaching to existing windows because it provides a cleaner debug environment (only development extensions). You would also need to launch Chrome with the remote debugging flag in order to attach to an existing instance.

## Creating a New Package

Expand All @@ -66,58 +78,73 @@ A standalone application with it's own entry point. Recommend copying the [embed

A component/library package that can be imported into other packages. Recommend copying the [components](./packages/components/) package, removing any dependencies and files not required.

## Browser Support
## Updating E2E Snapshots

Support is best for [Google Chrome](https://www.google.com/intl/en_ca/chrome/) and Chromium based browsers (such as [Microsoft Edge based on Chromium](https://www.microsoft.com/en-us/edge)). We try and maintain compatibility with [Mozilla Firefox](https://www.mozilla.org/en-CA/firefox/new/) and [Apple Safari](https://www.apple.com/ca/safari/) as well.
**Note:** You must have [Docker installed](https://docs.docker.com/get-docker/), and `deephaven-core` must already be running on port 10000 on your local machine for all e2e tests.

If you encounter an issue specific to a browser, check that your browser is up to date, then check issues labeled with [firefox](https://github.com/deephaven/web-client-ui/labels/firefox) or [safari](https://github.com/deephaven/web-client-ui/labels/safari) for a list of known browser compatibility issues before reporting the issue.
Snapshots are used by end-to-end tests to visually verify the output. Sometimes changes are made requiring snapshots to be updated. Before running snapshots locally, you must be running the development server with `npm start` or have run `npm run build` recently. Run snapshots locally by running `npm run e2e:update-snapshots`.

Once you are satisfied with the snapshots and everything is passing locally, you need to use a docker image to [update snapshots for CI](https://playwright.dev/docs/test-snapshots) (unless you are running the same platform as CI (Ubuntu)). Run `npm run e2e:update-ci-snapshots` which will mount the current directory into a docker image and re-run the tests from there. Test results will be written to your local directories.

# Releases

All new changes (bug fixes, feature requests) are merged to `main` so they are always included in the latest release. We use semantic versioning for major/minor/patch releases.

We use 3 release types

- `stable` - Stable releases are created periodically off of the `main` with the dist-tag `latest`. These will include an appropriate version bump and [release notes](https://github.com/deephaven/web-client-ui/releases), detailing the changes that are in that version.

- `nightly` - Nightly releases are published every night with the dist-tag `nightly` to npm. You can reference the nightly release to always be on the latest by referencing `nightly` as the version, though stability is not guaranteed, e.g. `npm install --save @deephaven/grid@nightly`.

- `hotfix` - For Long Term Support releases (versions we consume in the enterprise product), we create a new branch in Community matching the LTS version number (e.g. [release/v0.6](https://github.com/deephaven/web-client-ui/tree/release/v0.6)). Bug fixes/hotfixes are then either cherry-picked from `main` (if the fix has been merged to main), or directly merged into the hotfix branch (if code has changed in `main` and the fix only applies in the hotfix branch).

- `alpha`/`other` - For publishing WIP branches to NPM or testing CI/publishing changes. There is a GitHub Action called `Publish Alpha` which will prompt you for a `preid` and `ref` to create the alpha version. These will publish to `npm` under the `canary` tag. The version number will be `x.yy.z-alpha.0` or using the `preid` specified.

## Releasing a New Version

**Note:** Only repo admins can do this. These steps apply to `main` and any `release/*` branches.

We use [lerna](https://github.com/lerna/lerna) and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) to automatically handle incrementing the version, generate the changelog, and create the release.

1. Generate a [GitHub Personal access token](https://github.com/settings/tokens):

- Under `Repository Access`, select `Only select repositories` and add `deephaven/web-client-ui`.
- Under `Repository Permissions`, set `Access: Read and write` for `Contents`. This will be necessary to push your version bump and create the release.
- Copy the token created and replace `<token>` with it in the next step.
- Under `Repository Access`, select `Only select repositories` and add `deephaven/web-client-ui`.

2. Bump the version, update the changelog, and create a release: `GH_TOKEN=<token> npm run version-bump`
- Under `Repository Permissions`, set `Access: Read and write` for `Contents`. This will be necessary to push your version bump and create the release.

After the release is created, you can go to the [actions page](https://github.com/deephaven/web-client-ui/actions) to see the publish action being kicked off.
- Copy the token created and replace `<token>` with it in the next step.

## Release Strategy
2. Checkout the branch you want to release. `main` or `release/*`

All new changes (bug fixes, feature requests) are merged to `main` so they are always included in the latest release.
3. Run this npm script to bump the version, update the changelog, and create a release on GitHub: `GH_TOKEN=<token> npm run version-bump`

### Stable Releases
4. **IMPORTANT**: If releasing a `release/*` branch, you need to reset the `latest` tag on GitHub. To do that, go to the [releases page](https://github.com/deephaven/web-client-ui/releases) and find the release that is actually the `latest` based on the version `main` is on.

Stable releases are created periodically off of the `main` with the dist-tag `latest`. These will include an appropriate version bump and [release notes](https://github.com/deephaven/web-client-ui/releases), detailing the changes that are in that version.
- Click edit on the actual `latest` release

### Nightly Releases
- Check the box for `Set as the latest release`

Nightly releases are published every night with the dist-tag `nightly` to npm. You can reference the nightly release to always be on the latest by referencing `nightly` as the version, though stability is not guaranteed, e.g. `npm install --save @deephaven/grid@nightly`.
- Update release

### Hotfix Releases
This ensures that an older version doesn't get marked as `latest` on GitHub. It will not effect npm.

For Long Term Support releases, we create a new branch in Community matching the LTS version number (e.g. [v0.6](https://github.com/deephaven/web-client-ui/tree/v0.6)), then adding a matching [dist-tag](https://github.com/lerna/lerna/blob/main/commands/publish/README.md#--dist-tag-tag) to the [publish-packages.yml](.github/workflows/publish-packages.yml#L24) for that branch. Bug fixes/hotfixes are then either cherry-picked from `main` (if the fix has been merged to main), or directly merged into the hotfix branch (if code has changed in `main` and the fix only applies in the hotfix branch). Once the branch is pushed to origin, the publish step is kicked off by creating a release as instructed in the [Releasing a New Version](#releasing-a-new-version) section.
After the release is created, you can go to the [actions page](https://github.com/deephaven/web-client-ui/actions) to see the publish action being kicked off.

## Analyzing Bundle Size
## Creating a hotfix/LTS branch

When adding new features, it can be useful to analyze the final package size to see what's in the package. Use [source-map-explorer](https://www.npmjs.com/package/source-map-explorer) to see what's taking up the most size in the package. First run `npm run build` to build a production bundle, then run `npx source-map-explorer 'packages/<package-name>/build/static/js/*.js'`, e.g.:
**Note:** Only repo admins can do this since `release/*` branches are protected.

```
npm run build
npx source-map-explorer 'packages/code-studio/build/static/js/*.js'
```
For our enterprise product, we occasinally need to make hotfixes (patch releases) to older versions that the enterprise client depends on. Since it would be unwise to update an old version of enterprise to the newest community UI components, we keep hotfix `release/*` branches. There are a few steps to create one.

## Updating Snapshots
1. Checkout the tag for the release where the branch should fork.

**Note:** You must have [Docker installed](https://docs.docker.com/get-docker/), and `deephaven-core` must already be running on port 10000 on your local machine for all e2e tests.
2. Create a new branch from this point called `release/vX.YY`. If forking from `v0.31.1` then the branch is `release/v0.31`.

Snapshots are used by end-to-end tests to visually verify the output. Sometimes changes are made requiring snapshots to be updated. Before running snapshots locally, you must be running the development server with `npm start` or have run `npm run build` recently. Run snapshots locally by running `npm run e2e:update-snapshots`.
3. Change the `distTag` in `lerna.json` to `vX.YY` which corresponds to the version from the branch name. This will ensure packages are published to npm under the `distTag` instead of the default of `latest`.

Once you are satisfied with the snapshots and everything is passing locally, you need to use a docker image to [update snapshots for CI](https://playwright.dev/docs/test-snapshots) (unless you are running the same platform as CI (Ubuntu)). Run `npm run e2e:update-ci-snapshots` which will mount the current directory into a docker image and re-run the tests from there. Test results will be written to your local directories.
4. Commit and push the branch

Once the branch is pushed to origin, new commits will require PRs into the branch. To create a patch release, refer to the [Releasing a New Version](#releasing-a-new-version) section.

## Updating Dependencies

Expand All @@ -128,3 +155,18 @@ Periodically dependencies should be updated such that we're using the latest and
- Run a tool like [lerna-update-wizard](https://github.com/Anifacted/lerna-update-wizard) by running `npx lerna-update-wizard` to go through steps to automatically update all child packages, OR
- Manually update the `package.json` of all packages with that dependency to the latest version.
- When updating the major version of dependencies, be sure to check the release notes for any breaking changes/migration notes. After updating dependencies, run an `npm install` and `npm test` to make sure all tests pass.

## Analyzing Bundle Size

When adding new features, it can be useful to analyze the final package size to see what's in the package. Use [source-map-explorer](https://www.npmjs.com/package/source-map-explorer) to see what's taking up the most size in the package. First run `npm run build` to build a production bundle, then run `npx source-map-explorer 'packages/<package-name>/build/static/js/*.js'`, e.g.:

```
npm run build
npx source-map-explorer 'packages/code-studio/build/static/js/*.js'
```

## Browser Support

Support is best for [Google Chrome](https://www.google.com/intl/en_ca/chrome/) and Chromium based browsers (such as [Microsoft Edge based on Chromium](https://www.microsoft.com/en-us/edge)). We try and maintain compatibility with [Mozilla Firefox](https://www.mozilla.org/en-CA/firefox/new/) and [Apple Safari](https://www.apple.com/ca/safari/) as well.

If you encounter an issue specific to a browser, check that your browser is up to date, then check issues labeled with [firefox](https://github.com/deephaven/web-client-ui/labels/firefox) or [safari](https://github.com/deephaven/web-client-ui/labels/safari) for a list of known browser compatibility issues before reporting the issue.
Loading

0 comments on commit b0865eb

Please sign in to comment.