Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
247 lines (178 loc) · 5.41 KB

CONTRIBUTING.md

File metadata and controls

247 lines (178 loc) · 5.41 KB

Contributing to OpenBrowser

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

Table of Contents

Development Setup

Prerequisites

  • Node.js (>= 18.0.0)
  • pnpm (latest stable version)
  • Git

This project uses pnpm as its package manager. Please ensure you have it installed.

Setting Up the Development Environment

  1. Fork the repository

  2. Clone your fork:

    git clone https://github.com/your-username/openbrowser.git
cd openbrowser

  3. Install dependencies:

    pnpm install

  4. Run tests:

    pnpm test

Development Commands

  • pnpm test: Run tests
  • pnpm run build: Build the project
  • pnpm run format: Format code using Prettier
  • pnpm run format:check: Check if files are properly formatted

Branching Strategy

Branch Types

  • main: Production-ready code
  • feature/*: New features or enhancements (e.g., feature/workflow-parser)
  • fix/*: Bug fixes (e.g., fix/parsing-error)
  • refactor/*: Code refactoring without functionality changes
  • docs/*: Documentation changes
  • test/*: Adding or modifying tests
  • chore/*: Maintenance tasks
  • build/*: Changes affecting the build system

Branch Naming Convention

  • Use lowercase letters and hyphens
  • Start with the type followed by a descriptive name
  • Examples:
    • feature/json-parser
    • fix/validation-error
    • refactor/typescript-migration

Commit Message Guidelines

Format

<type>(<scope>): <subject>

<body>

<footer>

Type

Must be one of:

  • build: Changes affecting build system or external dependencies
  • chore: Maintenance tasks, tooling, or housekeeping
  • ci: CI configuration changes
  • docs: Documentation only changes
  • feat: A new feature
  • fix: A bug fix
  • perf: Performance improvement
  • refactor: Code change that neither fixes a bug nor adds a feature
  • style: Changes not affecting code meaning (formatting, missing semicolons, etc.)
  • test: Adding or correcting tests

Subject

  • Use imperative, present tense: "change" not "changed" nor "changes"
  • Don't capitalize the first letter
  • No period (.) at the end
  • Maximum 50 characters

Body

  • Optional
  • Use imperative, present tense
  • Include motivation for change and contrast with previous behavior
  • Wrap at 72 characters

Examples

feat(parser): add JSON workflow parser implementation

Add parser class with validation and schema support.
Includes bidirectional conversion between JSON and runtime objects.

Closes #123

fix(validation): handle circular dependencies in workflow

Previously, the validator would hang on circular dependencies.
Now it detects and reports them as validation errors.

Pull Request Process

  1. Rebase your branch onto the latest main:

    git checkout main
git pull upstream main
git checkout your-branch
git rebase main

  2. Fix up commits to maintain clean history:

    git rebase -i main

  3. Ensure:

    • All tests pass
    • Code is properly formatted
    • Documentation is updated
    • Commit messages follow guidelines

  4. Submit PR:

    • Use a clear title following commit message format
    • Include comprehensive description
    • Reference any related issues

  5. Address review feedback:

    • Fix issues in the original commits where they appear
    • Force push updates after rebasing
    • Don't add "fix review comments" commits

Code Style

We use Prettier to enforce consistent code formatting. The project comes with pre-configured Prettier settings.

Style Guidelines

  • Use 2 spaces for indentation
  • Maximum line length of 80 characters
  • Double quotes for strings
  • Semicolons are required
  • No trailing commas
  • Explicit function return types (enforced by TypeScript)
  • Explicit accessibility modifiers in classes

Examples

// Good
interface Config {
  name: string;
  options?: Record<string, unknown>;
}

export class Parser {
  private readonly config: Config;

  public constructor(config: Config) {
    this.config = config;
  }

  public parse(input: string): Record<string, unknown> {
    const result = this.processInput(input);
    return {
      name: this.config.name,
      result
    };
  }
}

// Bad - Various style issues
interface config {
  name: string;
  options?: any; // Avoid 'any'
}

export class parser {
  config: config; // Missing accessibility modifier
  constructor(config: config) {
    // Missing explicit 'public'
    this.config = config;
  } // Missing semicolon
}

Editor Setup

  1. Install the Prettier VS Code extension

  2. VS Code will automatically use the project's Prettier configuration

  3. Enable format on save in VS Code settings:

    {
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

Available Scripts

  • pnpm run format: Format code using Prettier
  • pnpm run format:check: Check if files are properly formatted

Questions?

If you have questions or need help, please:

  1. Check existing issues and documentation
  2. Create a new issue for discussion
  3. Ask in the project's communication channels

Thank you for contributing to OpenBrowser!