Skip to content

Commit 83b29c8

Browse files
goosewobblergoosewobbler
committed
docs: enhance setup and development documentation
- Added detailed sections on dependency management, including catalog purposes and commands for switching and updating catalogs in the setup.md file. - Updated development.md in the tauri-service and electron-service packages to reference the new setup documentation and streamline the setup process. - Improved clarity on prerequisites and setup instructions for developing the Tauri service.
1 parent 2c2dad1 commit 83b29c8

3 files changed

Lines changed: 141 additions & 438 deletions

File tree

‎docs/setup.md‎

Lines changed: 42 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -193,6 +193,44 @@ To use a catalog dependency:
193193
}
194194
```
195195

196+
## Dependency Management
197+
198+
The project uses three catalogs to test against different versions of key dependencies:
199+
200+
| Catalog | Purpose |
201+
|---------|---------|
202+
| `default` | Stable production versions — the reliable baseline |
203+
| `next` | Latest/nightly versions — validates upcoming compatibility |
204+
| `minimum` | Lowest supported versions — ensures backward compatibility |
205+
206+
### Switching Catalogs
207+
208+
```bash
209+
pnpm catalog:default # Switch all packages to stable versions
210+
pnpm catalog:next # Switch all packages to latest/nightly versions
211+
pnpm catalog:minimum # Switch all packages to lowest supported versions
212+
```
213+
214+
### Updating Catalog Versions
215+
216+
```bash
217+
# Update catalog versions interactively
218+
pnpm catalog:update
219+
220+
# Preview changes without applying them
221+
pnpm catalog:update:dry
222+
223+
# Update all catalogs and other dependencies
224+
pnpm update:all
225+
226+
# Target a specific catalog
227+
pnpm catalog:update --default
228+
pnpm catalog:update --next
229+
pnpm catalog:update --minimum
230+
```
231+
232+
The update process shows available updates, lets you select which to apply, updates `pnpm-workspace.yaml`, then runs `pnpm install`.
233+
196234
## Turborepo Caching
197235

198236
Turborepo caches task outputs to speed up subsequent runs.
@@ -236,11 +274,11 @@ pnpm turbo build
236274
### Update Dependencies
237275

238276
```bash
239-
# Update all dependencies
240-
pnpm update -r -i --latest
277+
# Update dependencies interactively
278+
pnpm update:interactive
241279

242-
# Update specific package
243-
pnpm --filter @wdio/electron-service update some-package
280+
# Preview changes without applying
281+
pnpm update:interactive:dry
244282
```
245283

246284
## Troubleshooting

‎packages/electron-service/docs/development.md‎

Lines changed: 57 additions & 194 deletions
Original file line numberDiff line numberDiff line change
@@ -1,253 +1,116 @@
11
# Development
22

3-
## Prerequisites
3+
## Setup
44

5-
Development and building the service locally requires [Node.JS](https://nodejs.org) (>= 18) with [PNPM](https://pnpm.io) as a package manager -- and Git, obviously.
6-
7-
To start with development, use e.g. [NVM](https://github.com/nvm-sh/nvm) to install an appropriate version of NodeJS, then [install PNPM](https://pnpm.io/installation). Once that is done you can check out the repo with git, and install the dependencies with PNPM.
8-
9-
[Husky](https://typicode.github.io/husky/) is used for git commit hooks in combination with [`lint-staged`](https://github.com/lint-staged/lint-staged).
10-
[Turborepo](https://turbo.build) is used to handle builds and testing.
5+
See the [Monorepo Setup Guide](../../docs/setup.md) for prerequisites, cloning, installing dependencies, building, and common workflows.
116

127
## Dependency Management
138

14-
The project uses a catalog system to manage dependencies across all packages. There are three catalogs:
15-
16-
1. **`default`**: Production-ready configuration using stable versions
17-
- Example: `electron: "catalog:default"` (resolves to version ^32.0.1)
18-
- Provides a reliable, well-tested baseline
19-
20-
2. **`next`**: Forward-looking configuration with latest versions
21-
- Example: `electron-nightly: "catalog:next"` (latest nightly builds)
22-
- Validates compatibility with upcoming changes
23-
24-
3. **`minimum`**: Lowest supported versions
25-
- Example: `electron: "catalog:minimum"` (version ^28.0.0)
26-
- Ensures backward compatibility
27-
28-
### Switching Catalogs
29-
30-
To switch all packages to use a specific catalog:
31-
32-
```bash
33-
# Switch to default catalog (stable versions)
34-
pnpm catalog:default
35-
36-
# Switch to next catalog (latest/nightly versions)
37-
pnpm catalog:next
38-
39-
# Switch to minimum catalog (lowest supported versions)
40-
pnpm catalog:minimum
41-
```
42-
43-
### Updating Catalog Versions
44-
45-
To update the versions in a catalog:
46-
47-
```bash
48-
# Update a specific catalog
49-
pnpm catalog:update
50-
51-
# Preview changes without applying them
52-
pnpm catalog:update:dry
53-
54-
# Update all catalogs and other dependencies
55-
pnpm update:all
56-
```
57-
58-
You can also specify the catalog directly using shortcuts:
9+
The project uses a catalog system to manage Electron versions across three catalogs:
5910

60-
```bash
61-
pnpm catalog:update --default # Update default catalog
62-
pnpm catalog:update --next # Update next catalog
63-
pnpm catalog:update --minimum # Update minimum catalog
64-
```
65-
66-
The update process will:
67-
68-
1. Show available updates for all packages in the selected catalog
69-
2. Allow you to select which packages to update
70-
3. Update the versions in the workspace file
71-
4. Run `pnpm install` to apply the changes
72-
73-
For the `next` catalog specifically, the update process will:
11+
| Catalog | Purpose | Example |
12+
|---------|---------|---------|
13+
| `default` | Stable production versions | `electron: "catalog:default"` → `^32.0.1` |
14+
| `next` | Latest/nightly builds | `electron-nightly: "catalog:next"` |
15+
| `minimum` | Lowest supported versions | `electron: "catalog:minimum"` → `^28.0.0` |
7416

75-
- Fetch the latest electron-nightly version from npm
76-
- Set other packages to use the most appropriate tag:
77-
- Checks all available tags (next, beta, alpha, latest)
78-
- Compares full semantic versions to find the highest version across all tags
79-
- Prioritizes cutting-edge tags in order: next > beta > alpha > latest
80-
- Remove the electron dependency since only electron-nightly is used in this catalog
17+
See [Dependency Management](../../docs/setup.md#dependency-management) for catalog switching and update commands.
8118

82-
## Rebuilding on file changes
19+
For the `next` catalog specifically, the update process:
20+
- Fetches the latest `electron-nightly` version from npm
21+
- Compares all available tags (next, beta, alpha, latest) by full semantic version
22+
- Prioritizes cutting-edge tags in order: next > beta > alpha > latest
23+
- Removes the `electron` dependency (only `electron-nightly` is used in this catalog)
8324

84-
During development, it is helpful to rebuild files as they change, with respect to all packages. To do this, run the dev script in a new terminal:
25+
## Development Mode
8526

8627
```bash
28+
# Rebuild all packages on changes
8729
pnpm dev
88-
```
89-
90-
Alternatively, you can run it for each individual package.
91-
For example, run the dev script for `@wdio/electron-utils` in a new terminal:
9230

93-
```bash
31+
# Rebuild a specific package
9432
pnpm dev --filter "@wdio/native-utils"
9533
```
9634

97-
## Testing - E2Es
35+
## Testing
9836

99-
E2E tests can be run locally via:
37+
### E2E Tests
10038

10139
```bash
10240
pnpm test:e2e-local
103-
```
104-
105-
```bash
10641
pnpm test:e2e-mac-universal-local
10742
```
10843

109-
Below are the task graphs for the E2Es:
44+
Task graphs:
11045

11146
![E2E Task Graph](../.github/assets/e2e-graph.png 'E2E Task Graph')
112-
11347
![Mac Universal E2E Task Graph](../.github/assets/e2e-graph-mac-universal.png 'Mac Universal E2E Task Graph')
11448

115-
Note: The E2E runner logs are saved per run in the configured `outputDir` and include service namespaces (e.g., `wdio-electron-service:service`). Enable debug output for all namespaces by setting `DEBUG=wdio-electron-service:*`.
116-
117-
All E2E test applications use [electron-vite](https://electron-vite.org) for modern development and building.
118-
119-
## Testing - Units
120-
121-
Unit tests (using [Vitest](https://vitest.dev/)) can be run via:
49+
Enable debug output for all namespaces:
12250

12351
```bash
124-
pnpm test:unit
52+
DEBUG=wdio-electron-service:* pnpm test:e2e-local
12553
```
12654

127-
...in the root to run all of the tests for each package, OR
128-
129-
```bash
130-
pnpm test:dev
131-
```
55+
All E2E test applications use [electron-vite](https://electron-vite.org).
13256

133-
...in each package directory to run tests in watch mode.
134-
135-
## Updating Dependencies
136-
137-
Dependencies can be updated interactively via:
138-
139-
```bash
140-
pnpm update:interactive
141-
```
142-
143-
and
144-
145-
```bash
146-
pnpm update:interactive:dry
147-
```
148-
149-
for a dry run.
150-
151-
## Updating E2E Task Graphs
152-
153-
Task graphs can be updated by running:
57+
### Update E2E Task Graphs
15458

15559
```bash
15660
pnpm graph
15761
```
15862

159-
## Formatting & Linting
160-
161-
The repo uses [Biome](https://biomejs.dev) for formatting and primary lint checks, alongside ESLint for additional rules.
162-
163-
- Format all files:
164-
165-
```bash
166-
pnpm format
167-
```
168-
169-
- Check formatting only (no writes):
63+
### Unit Tests
17064

17165
```bash
172-
pnpm format:check
173-
```
174-
175-
- Lint (Biome + ESLint):
176-
177-
```bash
178-
pnpm lint
179-
```
180-
181-
- Lint with fixes:
66+
# All unit tests (from repo root)
67+
pnpm test:unit
18268

183-
```bash
184-
pnpm lint:fix
69+
# Watch mode (from package directory)
70+
pnpm test:dev
18571
```
18672

187-
## Contributing
188-
189-
Check the issues or [raise a new one](https://github.com/webdriverio/desktop-mobile/issues/new) for discussion:
190-
191-
**[Help Wanted Issues](https://github.com/webdriverio/desktop-mobile/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22)**
192-
**[Good First Issues](https://github.com/webdriverio/desktop-mobile/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22good+first+issue%22)**
193-
19473
## Release
19574

196-
Project maintainers can publish a release or pre-release of the npm package by manually running the [`Manual NPM Publish`](https://github.com/webdriverio/desktop-mobile/actions/workflows/release.yml) GitHub workflow. They will choose the release type to trigger a `major` , `minor`, or `patch` release following [Semantic Versioning](https://semver.org/), or a pre-release.
197-
198-
For detailed information about our release management process, including milestone structure, labeling system, and workflow, see the [Release Management](./release-management.md) documentation.
199-
200-
## Release Process
75+
Project maintainers publish releases using GitHub Actions workflows. The project follows a feature branch strategy:
20176

202-
Project maintainers can publish releases using GitHub Actions workflows. The project follows a feature branch strategy with three main branch types, e.g.
77+
- `main` — current stable version
78+
- `feature/vX` — next major version development
79+
- `vX.x` — maintenance branch
20380

204-
- `main` - current stable version (e.g., v8.x)
205-
- `feature/v9` - next major version development (e.g. v9.0.0-next.0)
206-
- `v7.x` - maintenance/LTS branch
81+
### Pre-releases
20782

208-
### Publishing Pre-releases
83+
Run the [pre-release workflow](https://github.com/webdriverio/desktop-mobile/actions/workflows/pre-release.yml):
20984

210-
To publish a pre-release, run the [pre-release workflow](https://github.com/webdriverio/desktop-mobile/actions/workflows/pre-release.yml):
85+
1. Select branch (`feature` for next major, `main` for current version)
86+
2. Choose type: `prepatch`, `preminor`, `premajor`, or `prerelease`
87+
3. Optionally enable dry-run to preview changes
21188

212-
1. Select the branch:
213-
- `feature` for next major (automatically resolves to current feature branch, e.g., feature/v9)
214-
- `main` for current version pre-releases
215-
2. Choose the pre-release type:
216-
- `prepatch` - e.g., 8.2.4-alpha.0
217-
- `preminor` - e.g., 8.3.0-alpha.0
218-
- `premajor` - e.g., 9.0.0-alpha.0
219-
- `prerelease` - increment alpha/beta number
220-
3. Optionally enable dry-run mode to preview the changes
89+
### Releases
22190

222-
### Publishing Releases
91+
Run the [release workflow](https://github.com/webdriverio/desktop-mobile/actions/workflows/release.yml):
22392

224-
To publish a release, run the [release workflow](https://github.com/webdriverio/desktop-mobile/actions/workflows/release.yml):
225-
226-
1. Select the branch:
227-
- `main` for current stable releases
228-
- `feature` for major version releases (automatically resolves to current feature branch)
229-
- `maintenance` for LTS releases (automatically resolves to current maintenance branch)
230-
2. Choose the release type:
231-
- `patch` for bug fixes
232-
- `minor` for new features
233-
- `major` for breaking changes (only allowed from feature branch)
234-
3. Optionally enable dry-run mode to preview the changes
93+
1. Select branch (`main`, `feature`, or `maintenance`)
94+
2. Choose type: `patch`, `minor`, or `major`
95+
3. Optionally enable dry-run to preview changes
23596

23697
### Major Version Releases
23798

238-
When releasing a new major version (e.g., v9.0.0):
239-
24099
1. Ensure all changes are ready in the feature branch
241-
2. Run the release workflow with:
242-
- Branch: `feature`
243-
- Release type: `major`
244-
3. This will automatically:
245-
- Create maintenance branch for current version (e.g., `v8.x`)
246-
- Update dependabot configuration
247-
- Archive old maintenance branch
248-
- Merge feature branch to main
249-
- Create GitHub release
100+
2. Run the release workflow with branch `feature` and type `major`
101+
3. This automatically:
102+
- Creates a maintenance branch for the current version
103+
- Updates dependabot configuration
104+
- Merges the feature branch to main
105+
- Creates a GitHub release
250106

251107
### Maintenance Policy
252108

253-
This repository does not maintain LTS or maintenance branches. Each major version receives updates only while it is the current stable version on the `main` branch. Users requiring long-term support should pin to specific versions in their package.json.
109+
This repository does not maintain LTS or maintenance branches. Users requiring long-term support should pin to specific versions in their `package.json`.
110+
111+
## Contributing
112+
113+
See [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution guidelines, commit format, and PR process.
114+
115+
- **[Help Wanted Issues](https://github.com/webdriverio/desktop-mobile/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Ahelp%3Awanted+label%3Ascope%3Aelectron)**
116+
- **[Beginner Friendly Issues](https://github.com/webdriverio/desktop-mobile/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Ahelp%3Abeginner-friendly+label%3Ascope%3Aelectron)**

0 commit comments

Comments
 (0)