Skip to content

Latest commit

 

History

History
326 lines (226 loc) · 7.06 KB

CONTRIBUTING.md

File metadata and controls

326 lines (226 loc) · 7.06 KB

Contributing to WebdriverIO Desktop & Mobile Testing Services

Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to this project.

Code of Conduct

Please be respectful and constructive in all interactions. We aim to create a welcoming environment for all contributors.

Getting Started

Prerequisites

  • Node.js 18 LTS or 20 LTS
  • pnpm 10.27.0+
  • Git

Setup

  1. Fork the repository
  2. Clone your fork: 
    git clone https://github.com/YOUR_USERNAME/desktop-mobile.git
cd desktop-mobile
  3. Install dependencies: 
    pnpm install
  4. Build all packages: 
    pnpm turbo build
  5. Run tests to verify setup: 
    pnpm test

See docs/setup.md for detailed setup instructions.

Development Workflow

1. Create a Branch

Create a new branch for your changes:

git checkout -b feature/my-feature
# or
git checkout -b fix/my-bugfix

Branch naming conventions:

  • feature/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation changes
  • refactor/ - Code refactoring
  • test/ - Test improvements
  • chore/ - Build/tooling changes

2. Make Your Changes

  • Write code following our coding standards
  • Add tests for new functionality
  • Update documentation as needed
  • Ensure tests pass: pnpm test
  • Ensure linting passes: pnpm lint

3. Commit Your Changes

We use conventional commits for clear commit history:

git add .
git commit -m "feat: add new feature"

Commit message format:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Build process or tooling changes
  • perf: Performance improvements

Scope:

Scope by framework, not package name. Most changes that touch a service, its plugin, fixtures, and E2E tests are all part of the same logical unit of work. For cross-cutting changes, omit the scope.

# Framework-scoped (changes within one framework's ecosystem)
git commit -m "feat(tauri): complete mocking"
git commit -m "fix(electron): windows multiremote"

# No scope (cross-cutting or shared changes)
git commit -m "refactor: extract shared diagnostics to native-utils"
git commit -m "docs: update installation instructions"
git commit -m "chore: update deps"

4. Push and Create Pull Request

git push origin feature/my-feature

Then create a pull request on GitHub with:

  • Clear title describing the change
  • Description of what changed and why
  • Reference to any related issues
  • Screenshots (if applicable)

Coding Standards

TypeScript

  • Use TypeScript strict mode
  • Prefer undefined over null
  • Use ESM (ES Modules) everywhere
  • Avoid any - use proper types
  • JSDoc for public APIs only when necessary (prefer self-documenting code)

Code Style

  • Use 2 spaces for indentation
  • Use single quotes for strings
  • Use trailing commas in objects and arrays
  • Max line length: 120 characters
  • Use arrow functions for callbacks

Our linters (Biome and ESLint) will auto-fix most style issues:

pnpm lint:fix
pnpm format

Project Structure

  • No barrel files (index.ts with only re-exports) except in package roots
  • Avoid nested ternaries - extract logic for readability
  • Use meaningful names for files and directories
  • Keep files focused - one main export per file

Testing

Test Requirements

  • All code must have 80%+ test coverage
  • Write tests for:
    • New features
    • Bug fixes
    • Edge cases
    • Error handling

Writing Tests

We use Vitest for testing:

import { describe, expect, it, beforeEach, afterEach } from 'vitest';

describe('MyFeature', () => {
  it('should do something', () => {
    expect(doSomething()).toBe(expected);
  });

  it('should handle errors', () => {
    expect(() => doSomethingBad()).toThrow('Error message');
  });
});

Running Tests

# Run all tests
pnpm test

# Run tests for specific package
pnpm --filter @wdio/electron-service test

# Run tests with coverage
pnpm test:coverage

# Run tests in watch mode
pnpm --filter @wdio/electron-service vitest

Documentation

Code Documentation

  • JSDoc for public APIs only when necessary
  • Prefer self-documenting code over comments
  • No comments unless the logic isn't self-evident

README Files

  • Each package must have a comprehensive README
  • Include installation, usage, API docs, and examples
  • Keep READMEs up to date with code changes

Documentation Files

  • Update docs/ when adding new features
  • Add examples to examples/ directory
  • Update CHANGELOG.md for notable changes

Pull Request Process

Before Submitting

Ensure your PR passes all checks:

# Build all packages
pnpm turbo build

# Run linting
pnpm lint

# Run type checking
pnpm typecheck

# Run all tests
pnpm test

# Run tests with coverage
pnpm test:coverage

PR Checklist

  • Code follows project conventions
  • Tests added/updated and passing
  • Test coverage ≥ 80%
  • Documentation updated
  • Commit messages follow convention
  • No TypeScript errors
  • Linting passes
  • All CI checks passing

Review Process

  1. Maintainers will review your PR
  2. Address any requested changes
  3. Once approved, a maintainer will merge

Package-Specific Guidelines

Electron Service

When contributing to the Electron service:

  • Maintain backward compatibility
  • Test on Windows, macOS, and Linux
  • Test with both Electron Forge and Builder
  • Test with ESM and CJS configurations

Tauri Service

When contributing to the Tauri service:

  • Maintain backward compatibility with tauri-driver
  • Test on Windows, macOS, and Linux
  • Test with multiremote configurations
  • Ensure plugin communication works correctly
  • Test with various Tauri configuration patterns

Future Services

When new services are added, contribution guidelines will be updated as necessary.

Shared Utilities

When contributing to shared utilities:

  • Keep utilities framework-agnostic
  • Document extension points clearly
  • Consider impact on all services

Maintenance Policy

This repository does not maintain LTS or backport branches. Only the latest version on main receives updates. For details, see MAINTENANCE.md.

Release Process

Maintainers handle releases. The process is:

  1. Update version numbers
  2. Update CHANGELOG.md
  3. Create git tag
  4. Publish to npm

Getting Help

Recognition

Contributors will be:

  • Credited in CHANGELOG.md
  • Listed in package.json contributors
  • Recognized in release notes

Thank you for contributing! 🎉