Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
145 lines (107 loc) · 3.49 KB

CONTRIBUTING.md

File metadata and controls

145 lines (107 loc) · 3.49 KB

Contributing to Domscribe PHP

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

Code of Conduct

This project follows a Code of Conduct that all contributors are expected to adhere to. Please be respectful and constructive in all interactions.

How to Contribute

Reporting Bugs

If you find a bug, please create an issue on GitHub with:

  • A clear, descriptive title
  • Steps to reproduce the issue
  • Expected behavior
  • Actual behavior
  • PHP version and environment details
  • Code samples if applicable

Suggesting Enhancements

Enhancement suggestions are welcome! Please create an issue with:

  • A clear, descriptive title
  • Detailed explanation of the proposed feature
  • Use cases and examples
  • Why this enhancement would be useful

Pull Requests

  1. Fork the repository and create your branch from main
  2. Install dependencies: composer install
  3. Make your changes:
    • Follow PSR-12 coding standards
    • Add tests for new functionality
    • Update documentation as needed
  4. Run tests: composer test
  5. Run code quality checks:
    • composer cs-check - Check code style
    • composer phpstan - Run static analysis
  6. Commit your changes:
    • Use clear, descriptive commit messages
    • Reference issue numbers if applicable
  7. Push to your fork and submit a pull request

Development Setup

# Clone your fork
git clone https://github.com/your-username/domscribe-php.git
cd domscribe-php

# Install dependencies
composer install

# Run tests
composer test

# Check code style
composer cs-check

# Fix code style issues
composer cs-fix

# Run static analysis
composer phpstan

Coding Standards

  • Follow PSR-12 coding style
  • Use strict types: declare(strict_types=1);
  • Add PHPDoc comments for all public methods
  • Use type declarations for parameters and return types
  • Keep methods focused and concise
  • Write self-documenting code with clear variable names

Testing Guidelines

  • Write tests for all new functionality
  • Maintain or improve code coverage
  • Use descriptive test method names
  • Follow the Arrange-Act-Assert pattern
  • Test edge cases and error conditions

Example test:

public function testConvertSimpleParagraph(): void
{
    // Arrange
    $html = "<p>Test paragraph</p>";
    $expected = "Test paragraph.";

    // Act
    $result = Converter::htmlToMarkdown($html);

    // Assert
    $this->assertEquals($expected, trim($result));
}

Documentation

  • Update README.md for new features
  • Add examples in the examples/ directory
  • Keep documentation clear and concise
  • Include code examples where helpful

Commit Message Guidelines

Use clear, descriptive commit messages:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks

Examples:

feat: add support for custom node renderers
fix: handle empty table cells correctly
docs: update README with new examples
test: add tests for nested lists

Review Process

  • All submissions require review
  • We may suggest changes or improvements
  • Please respond to feedback in a timely manner
  • Once approved, your PR will be merged

Questions?

If you have questions, feel free to:

  • Open an issue for discussion
  • Reach out to the maintainers

Thank you for contributing to Domscribe PHP!