Skip to content

Latest commit

 

History

History
294 lines (192 loc) · 7.32 KB

CONTRIBUTING.md

File metadata and controls

294 lines (192 loc) · 7.32 KB

Midscene Contribution Guide

Thanks for showing interest in contributing to Midscene. Before starting your contribution, please take a moment to read the following guidelines.

Setup the Environment

Fork the Repo

Fork this repository to your own GitHub account and then clone it to your local machine.

Install Node.js

We recommend using Node.js 18.19.0. You can check your currently used Node.js version with the following command:

node -v

If you do not have Node.js installed in your current environment, you can use nvm or fnm to install it.

Here is an example of how to install the Node.js 18.19.0 version via nvm:

# Install the LTS version of Node.js 20
nvm install 18.19.0 --lts

# Make the newly installed Node.js 20 as the default version
nvm alias default 18.19.0

# Switch to the newly installed Node.js 20
nvm use 18.19.0

Install Dependencies

Enable pnpm with corepack:

corepack enable

Install dependencies:

pnpm install

What this will do:

  • Install all dependencies
  • Create symlinks between packages in the monorepo
  • Run the prepare script to build all packages, powered by nx.

Set Git Email

Please make sure you have your email set up in <https://github.com/settings/emails>. This will be needed later when you want to submit a pull request.

Check that your git client is already configured with the email:

git config --list | grep email

Set the email to global config:

git config --global user.email "[email protected]"

Set the email for local repo:

git config user.email "[email protected]"

Making Changes and Building

Once you have set up the local development environment in your forked repo, we can start development.

Checkout A New Branch

It is recommended to develop on a new branch, as it will make things easier later when you submit a pull request:

git checkout -b MY_BRANCH_NAME

Build the Package

Use nx build to build the package you want to change:

npx nx build @midscene/web

Build all packages:

pnpm run build

Testing

To change the AI-related code of this repository, you need to create a '.env 'file in the root directory, which reads as follows:

OPENAI_API_KEY="your_token"
MIDSCENE_MODEL_NAME="gpt-4o-2024-08-06"

Add New Tests

If you've fixed a bug or added code that should be tested, then add some tests.

You can add unit test cases in the <PACKAGE_DIR>/tests folder. The test runner is based on Vitest.

Run Unit Tests

Before submitting a pull request, it's important to make sure that the changes haven't introduced any regressions or bugs. You can run the unit tests for the project by executing the following command:

pnpm run test
# Test with AI-related features, it will need to create a .env file
pnpm run test:ai

You can also run the unit tests of a single package:

npx nx test @midscene/web
# Test with AI-related features, it will need to create a .env file
npx nx test:ai @midscene/web

Run E2E Tests

Midscene uses

  • playwright to run end-to-end tests.
  • adb to run end-to-end tests on Android.

You can run the e2e command to run E2E tests for playwright:

pnpm run e2e

If you need to run a specified test:

npx nx e2e @midscene/web

If you need to run E2E tests for adb:

Before running the test, you need to start the adb server first, please refer to the README.md for details.

cd packages/web-integration && pnpm run test:ai -- adb

Linting

To help maintain consistency and readability of the codebase, we use Biome to lint the codes.

You can run the linter by executing the following command:

pnpm run lint

For VS Code users, you can install the Biome VS Code extension to see lints while typing.

Documentation

You can find the Rsbuild documentation in the website folder.

Submitting Changes

Committing your Changes

Commit your changes to your forked repo, and create a pull request.

Normally, the commits in a PR will be squashed into one commit, so you don't need to rebase locally.

Format of PR titles

The format of PR titles follow Conventional Commits.

An example:

feat(core): Add `myOption` config
^    ^    ^
|    |    |__ Subject
|    |_______ Scope
|____________ Type

Versioning

All Midscene packages will use a fixed unified version.

The release notes are automatically generated by GitHub releases.

Releasing

Repository maintainers can publish a new version of all packages to npm.

Here are the steps to publish (we generally use CI for releases and avoid publishing npm packages locally):

  1. Run the release action.
  2. Generate the release notes.

Chrome DevTools Extension

Directory Structure

midscene/
├── apps/
│   ├── chrome-extension/     # Chrome extension application
│   │   ├── dist/            # Build output directory
│   │   ├── extension/       # Packaged Chrome extension directory
│   │   ├── scripts/         # Build and utility scripts
│   │   ├── src/             # Source code
│   │   │   ├── extension/   # Chrome extension-specific code
│   │   │   └── ...
│   │   ├── static/          # Static resources
│   │   └── ...
│   └── ...
├── packages/
│   ├── core/                # Core functionality
│   ├── visualizer/          # Visualization components
│   ├── web-integration/     # Web integration
│   └── ...
└── ...

Developing the Chrome DevTools Extension

The Chrome DevTools extension uses the Rsbuild build system. Development workflow is as follows:

  1. Build base packages:
# First build the base packages
pnpm run build
  1. Development mode:
# Navigate to chrome-extension directory
cd apps/chrome-extension

# Start the development server
pnpm run dev
  1. Build the extension:
# Build the Chrome extension
cd apps/chrome-extension
pnpm run build
  1. Install the extension:

The built dist directory can be directly installed as a Chrome extension. In Chrome browser:

  • Open chrome://extensions/
  • Enable "Developer mode" in the top-right corner
  • Click "Load unpacked" in the top-left corner
  • Select the apps/chrome-extension/dist directory

Alternatively, you can use the packaged extension:

  • Select the apps/chrome-extension/extension_output/midscene-extension-v{version}.zip file

For more detailed information, please refer to Chrome DevTools README.