Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
253 lines (178 loc) · 5.84 KB

CONTRIBUTING.md

File metadata and controls

253 lines (178 loc) · 5.84 KB

Contributing to React Split Pane

Bug Reports | Feature Requests | Pull Requests | Development Setup | Running Tests

Thank you for considering contributing to React Split Pane! Please take a moment to review this document to make the contribution process easy and effective.

Using the Issue Tracker

The issue tracker is the preferred channel for bug reports and feature requests. Please respect these guidelines:

  • Do not use the issue tracker for personal support requests.
  • Do not derail or troll issues. Keep discussions on topic.

Bug Reports

A bug is a demonstrable problem caused by the code in the repository. Good bug reports are extremely helpful!

Guidelines for bug reports:

  1. Search first — Check if the issue has already been reported.
  2. Test latest — Try to reproduce it using the latest master branch.
  3. Isolate — Create a minimal reproduction using CodeSandbox or StackBlitz.

A good bug report includes:

  • React Split Pane version
  • React version
  • Browser and OS
  • Steps to reproduce
  • Expected vs actual behavior
  • Link to reproduction

Feature Requests

Feature requests are welcome! Please provide:

  • Clear use case
  • Why existing features don't solve your problem
  • API suggestions (if applicable)
  • Examples from similar libraries (if applicable)

Pull Requests

Good pull requests are a fantastic help! They should remain focused and avoid unrelated changes.

Please ask first before starting significant work (new features, major refactoring). Open an issue to discuss your idea.

Pull Request Process

  1. Fork and clone the repository:

    git clone https://github.com/<your-username>/react-split-pane
cd react-split-pane
git remote add upstream https://github.com/tomkp/react-split-pane

  2. Create a branch from master:

    git checkout master
git pull upstream master
git checkout -b my-feature

  3. Install dependencies:

    npm install

  4. Make your changes, following the code style.

  5. Add tests for new functionality.

  6. Ensure all tests pass:

    npm test

  7. Ensure code passes linting:

    npm run lint

  8. Commit with a clear message:

    git commit -m "feat: add new feature"

  9. Push and open a pull request against master:

    git push origin my-feature

Commit Message Format

We follow Conventional Commits:

  • feat: — New feature
  • fix: — Bug fix
  • docs: — Documentation only
  • style: — Formatting, no code change
  • refactor: — Code change that neither fixes a bug nor adds a feature
  • test: — Adding or fixing tests
  • chore: — Build process or auxiliary tools

Development Setup

Prerequisites

  • Node.js 20+
  • npm 9+

Setup

# Clone the repository
git clone https://github.com/tomkp/react-split-pane
cd react-split-pane

# Install dependencies
npm install

# Start the development server (examples)
npm run dev

The examples will be available at http://localhost:5173

Project Structure

src/
├── components/       # React components (SplitPane, Pane, Divider)
├── hooks/           # React hooks (useResizer, useKeyboardResize)
├── types/           # TypeScript type definitions
├── utils/           # Utility functions
├── test/            # Test setup
└── index.ts         # Main entry point

examples/            # Example applications

Available Scripts

Command Description
npm run dev Start examples dev server
npm test Run tests
npm run test:watch Run tests in watch mode
npm run lint Run ESLint
npm run build Build for production
npm run typecheck Run TypeScript type checking

Running Tests

All tests must pass before a pull request will be merged.

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Writing Tests

  • Place tests next to the code they test (e.g., useResizer.test.ts)
  • Use descriptive test names
  • Test both success and error cases
  • For hooks, use @testing-library/react and renderHook

Example:

import { describe, it, expect } from 'vitest';
import { renderHook } from '@testing-library/react';
import { useResizer } from './useResizer';

describe('useResizer', () => {
  it('initializes with provided sizes', () => {
    const { result } = renderHook(() =>
      useResizer({
        direction: 'horizontal',
        sizes: [300, 700],
        minSizes: [100, 100],
        maxSizes: [500, 900],
      })
    );

    expect(result.current.currentSizes).toEqual([300, 700]);
  });
});

Code Style

  • TypeScript — All code must be typed
  • ESLint — Run npm run lint before committing
  • Prettier — Code is auto-formatted
  • No any — Avoid any types; use unknown if necessary
  • Functional — Prefer functional components and hooks
  • Comments — Add JSDoc comments to exported functions

Example Component

import type { CSSProperties } from 'react';

interface MyComponentProps {
  /** Description of the prop */
  value: string;
  /** Optional prop with default */
  size?: number;
}

/**
 * Description of the component.
 *
 * @example
 * ```tsx
 * <MyComponent value="hello" />
 * ```
 */
export function MyComponent({ value, size = 10 }: MyComponentProps) {
  // Implementation
}

License

By contributing, you agree to license your work under the MIT License.