Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
129 lines (89 loc) · 3.27 KB

CONTRIBUTING.md

File metadata and controls

129 lines (89 loc) · 3.27 KB

Contributing to PublicSuffix for Ruby

Thank you for your interest in contributing to PublicSuffix for Ruby!

Development Workflow

  1. Fork and clone the repository
  2. Install dependencies: bundle install
  3. Create a branch: git checkout -b feature/your-feature
  4. Make your changes
  5. Run tests: rake test
  6. Commit using Conventional Commits format (see below)
  7. Push and create a pull request

Commit Message Guidelines

We follow the Conventional Commits specification for commit messages, with a capitalized description. Use the project-specific conventions below.

Format

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

[optional body]

[optional footer(s)]

Type

  • feat: A new feature
  • fix: A bug fix
  • chore: Other changes that don't modify src or test files
  • docs: Documentation only changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code change that neither fixes a bug nor adds a feature
  • perf: Performance improvement
  • test: Adding or updating tests
  • build: Changes to build system or external dependencies
  • ci: Changes to CI configuration files and scripts

Scope

  • parser: List parsing and rule handling
  • domain: Domain parsing and validation
  • list: List management and operations
  • rule: Rule definitions and matching

Examples

feat(parser): Add support for wildcard exceptions

fix(domain): Handle FQDN trailing dots correctly

docs: Update usage examples in README

refactor(list): Simplify rule lookup logic

Breaking Changes

Add BREAKING CHANGE: in the footer:

feat(domain): Change parse return type

BREAKING CHANGE: Domain#parse now returns nil for invalid domains instead of raising.
Update code to check for nil returns.

Changelog

We follow the Common Changelog format for changelog entries.

Testing

Running Tests

rake test                        # Run all tests
rake test TEST=test/domain_test.rb  # Run specific test file

Writing Tests

  • Tests use Minitest framework
  • Place tests in test/ directory
  • Use descriptive test names
  • Test both happy paths and error cases
  • Include tests for edge cases (empty strings, unicode, etc.)

Pull Request Process

  1. Update documentation for API changes
  2. Add tests for new features or bug fixes
  3. Ensure all tests pass: rake test
  4. Use Conventional Commits format
  5. Provide clear PR description with context
  6. Reference related issues if applicable

Code Style

  • Follow Ruby Style Guide
  • Use RuboCop configuration if present
  • Add YARD documentation for public methods
  • Keep methods focused and small

Ruby-Specific Guidelines

  • Follow idiomatic Ruby patterns
  • Use meaningful variable and method names
  • Prefer raise over fail
  • Use blocks and iterators effectively
  • Follow the principle of least surprise
  • Prefer methods that return values over side effects

Documentation

  • Add YARD comments for public methods
  • Include usage examples in documentation
  • Update README.md for user-facing changes
  • Keep inline comments minimal - prefer self-documenting code

Questions?

Open an issue for questions, feature discussions, or bug reports.

Thank you for contributing!