# Contributing to tc-lib-file

Thank you for your interest in contributing to **tc-lib-file**.  
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-file.git
cd tc-lib-file
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-file/issues)** to avoid duplicates.

If no existing issue matches, [open a new one](https://github.com/tecnickcom/tc-lib-file/issues/new) and include:

- A **clear title and description** of the problem.
- The **library version** (`composer show tecnickcom/tc-lib-file`) 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-file/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-file/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/FileTest.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/`.

### Sandboxed / network-restricted environments

`FileTest` starts a local `php -S` HTTP server (via `proc_open`) so the cURL
tests can hit a real endpoint over loopback. The startup is bounded and falls
back to skipping those tests if the server cannot be reached, but in
environments that block loopback networking or forbid spawning a child process
you can skip that part outright:

```bash
TC_LIB_FILE_SKIP_HTTP_SERVER=1 make test
```

The four server-dependent tests are then reported as **skipped** instead of
running.

### Cross-platform behavior

Continuous integration runs on **Linux only**. Windows- and macOS-specific
behavior (path case-sensitivity, Unicode normalization, binary read mode) is
therefore exercised on the Linux runner through the injectable
`caseSensitivePaths` override and platform-parameterized helpers, and validated
manually on those operating systems. When changing path-handling code, keep it
drivable from a Linux test — assert both case-sensitive and case-insensitive
modes via the override rather than relying on the host OS — and avoid hardcoding
platform-specific paths (use `sys_get_temp_dir()` and `DIRECTORY_SEPARATOR`, and
compare `realpath()` on both sides). See the "Platform notes" section of the
[README](README.md) for the supported behaviors.

---

## 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-file/discussions) or contact the maintainer at [info@tecnick.com](mailto:info@tecnick.com).