Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
194 lines (132 loc) · 6.3 KB

CONTRIBUTING.md

File metadata and controls

194 lines (132 loc) · 6.3 KB

Contributing to tc-lib-unicode-data

Thank you for your interest in contributing to tc-lib-unicode-data.
Contributions of all kinds are welcome: bug reports, bug fixes, documentation improvements, new features, and refactors.

Please take a moment to read this guide before opening an issue or pull request.

Table of Contents

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating you agree to abide by its terms. Please report unacceptable behaviour to info@tecnick.com.

Security Vulnerabilities

Do not open a public GitHub issue for security vulnerabilities.
Please follow the Security Policy and report them privately.

Getting Started

Requirements

  • PHP ≥ 8.1
  • Composer v2
  • make, git
  • Optional: rpmbuild (RPM packaging), dpkg-buildpackage (DEB packaging)

Local setup

git clone https://github.com/tecnickcom/tc-lib-unicode-data.git
cd tc-lib-unicode-data
make buildall

To verify everything is working after a change:

make qa

This runs linting, static analysis, and the full unit-test suite with coverage.

Reporting a Bug

Before opening an issue:

  1. Check the Security Policy — if the bug is a security vulnerability, do not file a public issue.
  2. Search existing issues to avoid duplicates.

If no existing issue matches, open a new one and include:

  • A clear title and description of the problem.
  • The library version (composer show tecnickcom/tc-lib-unicode-data) and PHP version.
  • A minimal, self-contained reproduction — a short PHP script or a failing PHPUnit test case is ideal.
  • Expected vs. actual behaviour — what you expected to happen and what actually happened.
  • Any relevant stack trace or error output.

The more precise and reproducible the report, the faster it can be triaged and fixed.

Submitting a Bug Fix

  1. Fork the repository and create a branch from main: 
    git checkout -b fix/short-description-of-bug
  2. Make your changes, following the Coding Standards below.
  3. Add or update unit tests to cover the changes.
  4. Run the full quality-assurance suite locally and ensure it passes: 
    make qa
  5. Commit your changes (see Commit Message Guidelines).
  6. Open a pull request against main and fill in the PR template:
    • Describe the problem and your solution.
    • Reference the related issue number (e.g. Fixes #123).

Proposing a New Feature

Before writing any code:

  1. Open a Feature Request on GitHub Issues describing the use case and proposed API.
  2. Wait for feedback from the maintainer. This avoids investing time in a direction that may not be accepted.

Once the feature is agreed upon, follow the same branch → code → test → PR workflow as for bug fixes, using a branch named feature/short-description.

Development Workflow

The Makefile exposes all common development tasks:

Command Description
make qa Run linting, static analysis, tests, and reports
make test Run PHPUnit with code coverage
make lint Check coding standards (PHPCS, PHPMD, PHPStan)
make codefix Auto-fix coding standard violations (PHPCBF)
make buildall Install dependencies, fix style, run QA, and build packages
make clean Remove vendor/ and target/ directories
make server Start the built-in PHP development server for the examples

Run make help to see the full list of available targets.

Coding Standards

  • The codebase follows PSR-12 for formatting.
  • Run make codefix to auto-fix style violations before committing.
  • Run make lint to catch remaining issues (PHPCS, PHPMD, PHPStan).
  • All source files live under src/, all tests under test/.
  • Use strict types and explicit visibility on all class members.
  • Avoid introducing new external dependencies without prior discussion.

Testing

Tests are written with PHPUnit and live in test/.

# Run the full test suite with coverage
make test

# Run a specific test file
XDEBUG_MODE=coverage ./vendor/bin/phpunit test/HTMLTest.php

Requirements for contributions:

  • Every bug fix must be accompanied by a regression test that fails before the fix and passes after.
  • Every new feature must be accompanied by tests that cover both the happy path and edge cases.

Coverage reports are generated in target/coverage/.

Pull Request Guidelines

  • Target the main branch.
  • Keep PRs focused — one fix or feature per PR.
  • Ensure make qa passes locally before opening the PR.
  • Do not bump the version number in your PR; that is handled by the maintainer at release time.
  • Be responsive to review feedback; stale PRs may be closed after an extended period of inactivity.

Commit Message Guidelines

Use concise, imperative-mood commit messages:

fix: correct path traversal in font loader
feat: add support for XYZ
test: add regression test for #123
docs: update CONTRIBUTING workflow
refactor: extract text measurement into helper

Prefix tags: fix, feat, test, docs, refactor, chore, ci.
Reference issues where relevant: fix: correct X (closes #42).

Questions?

If you have a question that is not covered here, feel free to open a GitHub Discussion or contact the maintainer at info@tecnick.com.