Skip to content

Commit b0865eb

Browse files
mattrunyonmattrunyon
authored
chore: Update readme and add distTag to lerna config (#1175)
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.
1 parent 2ac25ae commit b0865eb

5 files changed

Lines changed: 112 additions & 63 deletions

File tree

‎.gitignore‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,6 @@
1414
.vscode/*
1515
!.vscode/settings.json
1616
!.vscode/tasks.json
17-
!.vscode/launch.json
1817
!.vscode/extensions.json
1918
!.vscode/*.code-snippets
2019
.DS_Store

‎.vscode/launch.json‎

Lines changed: 0 additions & 16 deletions
This file was deleted.

‎.vscode/settings.json‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,5 +8,24 @@
88
}
99
],
1010
"editor.defaultFormatter": "esbenp.prettier-vscode",
11-
"stylelint.validate": ["css", "html", "sass", "scss"]
12-
}
11+
"stylelint.validate": [
12+
"css",
13+
"html",
14+
"sass",
15+
"scss"
16+
],
17+
"launch": {
18+
"version": "0.2.0",
19+
"configurations": [
20+
{
21+
"name": "Launch Deephaven",
22+
"request": "launch",
23+
"type": "chrome",
24+
"url": "http://localhost:4000",
25+
"webRoot": "${workspaceFolder}",
26+
"userDataDir": "${workspaceFolder}/.vscode/chrome-debug-profile"
27+
}
28+
],
29+
"compounds": []
30+
}
31+
}

‎README.md‎

Lines changed: 85 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,38 @@ We're using a monorepo to manage our packages, as it becomes cumbersome to manag
44

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

7-
## Development Environment
7+
## Package Overview
88

9-
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.
9+
There are many packages located in the [packages](./packages) directory. A few of the more important ones are:
1010

11-
Use Chrome for debugging, install the React and Redux extensions.
11+
- [@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.
12+
- [@deephaven/components](./packages/components): Component library used within the web UI.
13+
- [@deephaven/grid](./packages/grid): High-performance grid component used to display large tables of data.
14+
- [@deephaven/dashboard](./packages/dashboard/): Dashboards used in [@deephaven/code-studio](./packages/code-studio) for displaying and organizing panels.
15+
- [@deephaven/golden-layout](./packages/golden-layout): Layout framework used in [@deephaven/dashboard](./packages/dashboard/).
1216

13-
- [React Developer Tools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi): Allows inspection/changing the props/state of react components.
14-
- [Redux DevTools](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=en): Inspect the redux store data.
17+
## Contributing
18+
19+
For details on how to contribute to this repository, please see the [contributing guidelines](./CONTRIBUTING.md).
20+
21+
# Development
1522

1623
## Getting Started
1724

18-
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/).
25+
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/).
26+
27+
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/).
28+
29+
## Recommended Environment
30+
31+
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.
32+
33+
We use Chrome for development with the React and Redux extensions.
1934

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

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

43-
## Package Overview
61+
## Debugging from VSCode
4462

45-
There are many packages located in the [packages](./packages) directory. A few of the more important ones are:
46-
47-
- [@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.
48-
- [@deephaven/components](./packages/components): Component library used within the web UI.
49-
- [@deephaven/grid](./packages/grid): High-performance grid component used to display large tables of data.
50-
- [@deephaven/dashboard](./packages/dashboard/): Dashboards used in [@deephaven/code-studio](./packages/code-studio) for displaying and organizing panels.
51-
- [@deephaven/golden-layout](./packages/golden-layout): Layout framework used in [@deephaven/dashboard](./packages/dashboard/).
63+
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.
5264

53-
## Contributing
65+
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.
5466

55-
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).
67+
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.
5668

5769
## Creating a New Package
5870

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

6779
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.
6880

69-
## Browser Support
81+
## Updating E2E Snapshots
7082

71-
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.
83+
**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.
7284

73-
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.
85+
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`.
86+
87+
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.
88+
89+
# Releases
90+
91+
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.
92+
93+
We use 3 release types
94+
95+
- `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.
96+
97+
- `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`.
98+
99+
- `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).
100+
101+
- `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.
74102

75103
## Releasing a New Version
76104

105+
**Note:** Only repo admins can do this. These steps apply to `main` and any `release/*` branches.
106+
77107
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.
78108

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

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

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

87-
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.
115+
- Copy the token created and replace `<token>` with it in the next step.
88116

89-
## Release Strategy
117+
2. Checkout the branch you want to release. `main` or `release/*`
90118

91-
All new changes (bug fixes, feature requests) are merged to `main` so they are always included in the latest release.
119+
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`
92120

93-
### Stable Releases
121+
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.
94122

95-
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.
123+
- Click edit on the actual `latest` release
96124

97-
### Nightly Releases
125+
- Check the box for `Set as the latest release`
98126

99-
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`.
127+
- Update release
100128

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

103-
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.
131+
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.
104132

105-
## Analyzing Bundle Size
133+
## Creating a hotfix/LTS branch
106134

107-
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.:
135+
**Note:** Only repo admins can do this since `release/*` branches are protected.
108136

109-
```
110-
npm run build
111-
npx source-map-explorer 'packages/code-studio/build/static/js/*.js'
112-
```
137+
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.
113138

114-
## Updating Snapshots
139+
1. Checkout the tag for the release where the branch should fork.
115140

116-
**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.
141+
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`.
117142

118-
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`.
143+
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`.
119144

120-
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.
145+
4. Commit and push the branch
146+
147+
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.
121148

122149
## Updating Dependencies
123150

@@ -128,3 +155,18 @@ Periodically dependencies should be updated such that we're using the latest and
128155
- 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
129156
- Manually update the `package.json` of all packages with that dependency to the latest version.
130157
- 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.
158+
159+
## Analyzing Bundle Size
160+
161+
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.:
162+
163+
```
164+
npm run build
165+
npx source-map-explorer 'packages/code-studio/build/static/js/*.js'
166+
```
167+
168+
## Browser Support
169+
170+
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.
171+
172+
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.

0 commit comments

Comments
 (0)
⚡