# 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](#code-of-conduct)
- [Security Vulnerabilities](#security-vulnerabilities)
- [Getting Started](#getting-started)
- [Reporting a Bug](#reporting-a-bug)
- [Submitting a Bug Fix](#submitting-a-bug-fix)
- [Proposing a New Feature](#proposing-a-new-feature)
- [Development Workflow](#development-workflow)
- [Coding Standards](#coding-standards)
- [Testing](#testing)
- [Pull Request Guidelines](#pull-request-guidelines)
- [Commit Message Guidelines](#commit-message-guidelines)

---

## Code of Conduct

This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating you agree to abide by its terms. Please report unacceptable behaviour to [info@tecnick.com](mailto:info@tecnick.com).

---

## Security Vulnerabilities

**Do not open a public GitHub issue for security vulnerabilities.**  
Please follow the [Security Policy](SECURITY.md) and report them privately.

---

## Getting Started

### Requirements

- PHP **≥ 8.2**
- [Composer](https://getcomposer.org/) v2
- `make`, `git`
- Optional: `rpmbuild` (RPM packaging), `dpkg-buildpackage` (DEB packaging)

### Local setup

```bash
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:

```bash
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](SECURITY.md)** — if the bug is a security vulnerability, do not file a public issue.
2. **Search [existing issues](https://github.com/tecnickcom/tc-lib-unicode-data/issues)** to avoid duplicates.

If no existing issue matches, [open a new one](https://github.com/tecnickcom/tc-lib-unicode-data/issues/new) 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](https://github.com/tecnickcom/tc-lib-unicode-data/fork) and create a branch from `main`:
   ```bash
   git checkout -b fix/short-description-of-bug
   ```
2. Make your changes, following the [Coding Standards](#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:
   ```bash
   make qa
   ```
5. Commit your changes (see [Commit Message Guidelines](#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](https://github.com/tecnickcom/tc-lib-unicode-data/issues/new) 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 |
| `make format` | Auto-format the code |
| `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 format` to auto-format the code.
- Run `make lint` to catch remaining issues.
- 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](https://phpunit.de/) and live in `test/`.

```bash
# 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](https://github.com/tecnickcom/tc-lib-unicode-data/discussions) or contact the maintainer at [info@tecnick.com](mailto:info@tecnick.com).