Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
353 lines (256 loc) · 9.78 KB

CONTRIBUTING.md

File metadata and controls

353 lines (256 loc) · 9.78 KB
Raw

Contributing to React Image Editor

Thank you for your interest in contributing to React Image Editor! 🎉

We welcome contributions of all kinds, from bug reports and feature requests to code contributions and documentation improvements.

📋 Table of Contents

📜 Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to yuis.ice@example.com.

🚀 Getting Started

Prerequisites

  • Node.js: Version 18 or higher
  • npm: Version 8 or higher (comes with Node.js)
  • Git: For version control

Quick Start

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR_USERNAME/react-image-editor.git
cd react-image-editor
  3. Install dependencies: 
    npm install
  4. Start the development server: 
    npm run dev
  5. Open your browser to http://localhost:5174

🤝 How to Contribute

🐛 Reporting Bugs

  1. Search existing issues to avoid duplicates
  2. Use the bug report template when creating a new issue
  3. Provide detailed information: OS, browser, steps to reproduce, etc.
  4. Include screenshots or videos if applicable

✨ Requesting Features

  1. Search existing feature requests to avoid duplicates
  2. Use the feature request template when creating a new request
  3. Explain your use case and why this feature would be valuable
  4. Consider starting a discussion first for major features

💻 Contributing Code

  1. Find an issue to work on or create one
  2. Comment on the issue to let others know you're working on it
  3. Fork and clone the repository
  4. Create a new branch for your feature or fix
  5. Make your changes following our coding guidelines
  6. Write tests for your changes
  7. Submit a pull request using our template

📖 Improving Documentation

  • Fix typos or clarify existing documentation
  • Add examples or tutorials
  • Improve API documentation
  • Translate documentation to other languages

🛠️ Development Setup

Project Structure

react-image-editor/
├── src/
│   ├── components/          # React components
│   ├── store/              # Zustand state management
│   ├── utils/              # Utility functions
│   ├── styles/             # CSS styles
│   └── types/              # TypeScript type definitions
├── public/                 # Static assets
├── docs/                   # Documentation
└── tests/                  # Test files

Available Scripts

  • npm run dev - Start development server
  • npm run build - Build for production
  • npm run preview - Preview production build
  • npm run lint - Run ESLint
  • npm run type-check - Run TypeScript checks
  • npm test - Run tests

Environment Setup

  1. Create a .env file (optional):

    VITE_APP_NAME=React Image Editor
VITE_DEBUG=true

  2. VS Code Extensions (recommended):

    • TypeScript and JavaScript Language Features
    • ESLint
    • Prettier
    • Auto Rename Tag
    • Bracket Pair Colorizer

📝 Coding Guidelines

TypeScript

  • Use strict TypeScript configuration
  • Define interfaces for all props and state
  • Use type-only imports when appropriate: 
    import type { ImageState } from './types';

React

  • Use functional components with hooks
  • Prefer React.useRef for canvas element access
  • Use React.memo for performance optimization when needed
  • Follow React Hooks rules

Canvas API

  • Use Canvas API directly instead of external libraries
  • Implement pixel manipulation using ImageData for filters
  • Ensure performance optimization for large images
  • Handle browser compatibility considerations

State Management

  • Use Zustand for global state
  • Keep state minimal and normalized
  • Implement proper undo/redo functionality
  • Use immer for immutable updates when needed

Styling

  • Use CSS modules or styled-components for component styles
  • Follow BEM methodology for CSS class naming
  • Ensure responsive design principles
  • Support dark/light themes

File Organization

  • Group related files in the same directory
  • Use index.ts files for clean imports
  • Keep components small and focused
  • Separate business logic from UI components

💬 Commit Message Guidelines

We follow the Conventional Commits specification:

Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing tests or correcting existing tests
  • chore: Changes to the build process or auxiliary tools

Examples

feat(filters): add sepia filter effect

Add sepia tone filter with adjustable intensity parameter.
Implements canvas-based pixel manipulation for vintage effect.

Closes #42
fix(crop): prevent negative crop dimensions

- Add validation for crop coordinates
- Ensure minimum crop size of 1x1 pixels
- Display user-friendly error messages

Fixes #38

🔄 Pull Request Process

Before Submitting

  1. Sync with upstream: Rebase your branch on the latest main
  2. Run tests: Ensure all tests pass
  3. Check linting: Run ESLint and fix any issues
  4. Test manually: Verify your changes work as expected
  5. Update documentation: Add or update relevant docs

Pull Request Checklist

  • Clear title and description
  • Link to related issues
  • Include screenshots for UI changes
  • Add tests for new functionality
  • Update documentation if needed
  • Follow coding guidelines
  • Pass all CI checks

Review Process

  1. Automated checks must pass (CI, tests, linting)
  2. Code review by at least one maintainer
  3. Manual testing for significant changes
  4. Documentation review if applicable
  5. Final approval and merge

🧪 Testing

Test Strategy

  • Unit tests for utility functions
  • Component tests for React components
  • Integration tests for user workflows
  • Visual regression tests for UI changes
  • Performance tests for image processing

Writing Tests

// Example component test
import { render, screen } from '@testing-library/react';
import { FilterPanel } from './FilterPanel';

test('renders brightness slider', () => {
  render(<FilterPanel />);
  const slider = screen.getByLabelText(/brightness/i);
  expect(slider).toBeInTheDocument();
});

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run specific test file
npm test FilterPanel.test.tsx

📚 Documentation

Types of Documentation

  • README.md: Project overview and quick start
  • API Documentation: Function and component APIs
  • Tutorials: Step-by-step guides
  • Examples: Code examples and demos
  • Contributing Guide: This document

Documentation Standards

  • Use clear, concise language
  • Include code examples
  • Add screenshots for visual features
  • Keep up-to-date with code changes
  • Support multiple languages when possible

📄 Contributor License Agreement

By contributing to React Image Editor, you agree that:

  1. Your contributions will be licensed under the MIT License
  2. You have the right to submit the code
  3. Your contributions are your own work or properly attributed
  4. You grant us a perpetual, worldwide, non-exclusive, royalty-free license to use your contributions

This is automatically agreed to when you submit a pull request.

🆘 Getting Help

Communication Channels

Common Questions

Q: How do I add a new image filter? A: Check out the FilterPanel.tsx and imageProcessor.ts files for examples.

Q: Can I use external image processing libraries? A: We prefer Canvas API for consistency, but exceptions can be made for complex features.

Q: How do I test my changes with different image formats? A: Use the test images in the public/test-images/ directory.

Resources

🙏 Recognition

Contributors will be recognized in:

  • README.md contributors section
  • GitHub contributors page
  • Release notes for significant contributions
  • Hall of Fame for outstanding contributions

Thank you for contributing to React Image Editor! Your efforts help make this project better for everyone. 🚀