# Contributing to Pluscare

This guide defines the conventions for Pull Requests. The goal is to keep the
process consistent and reviews fast. These are guidelines, not hard blockers:
use them as a reference standard.

## Workflow

1. Create a dedicated branch off `main`.
2. Open the PR against `main`: the description template is filled in
   automatically, complete all the relevant sections.

## PR title convention

Use the [Conventional Commits](https://www.conventionalcommits.org/) format:

```
<type>: <short description in English>
```

Allowed types:

| Type       | When to use it                                     |
|------------|----------------------------------------------------|
| `feat`     | New feature                                        |
| `fix`      | Bug fix                                            |
| `refactor` | Refactor with no functional changes                |
| `docs`     | Documentation only                                 |
| `chore`    | Maintenance, dependencies, config                  |
| `ci`       | Pipeline / DevOps                                  |
| `test`     | Adding or changing tests                           |

Examples:

```
feat: add PDF report for export
fix: invoices taxes calculation
chore: update composer dependencies
```

## Versioning

Semver tags are created automatically on deploy to `production`. The deploy
workflow runs `scripts/compute-version.sh`, which reads commit messages since
the last tag and bumps the version:

| Commit signal | Bump |
|---------------|------|
| `BREAKING CHANGE` or `type!:` in the message | major |
| `feat:` | minor |
| anything else (including `fix:`, `chore:`, etc.) | patch |

The version does **not** depend on opening a PR. What matters is that commits
on the deployed branch use Conventional Commit messages. Direct commits to
`main`, classic merges, and squash merges from PRs all work.

- **Production**: a new tag (e.g. `v1.3.0`) is created and pushed; `SENTRY_RELEASE` is set to that tag.
- **Testing**: no tag is created; `SENTRY_RELEASE` is set to `git describe` (e.g. `v1.2.0-3-gabc123`).

If commit messages are not conventional, the default bump is `patch`. For the
most reliable bumps when using PRs, enable squash merge with the PR title as
the commit message on GitHub.

## Checks to run locally before opening the PR

The same checks run in CI (`Quality` workflow):

```bash
composer analyse        # PHPStan / Larastan (level 5)
npm run check           # ESLint + TypeScript
php artisan test        # Test suite
composer test:coverage  # Test suite + minimum PHP coverage threshold (45%)
```

With Sail:

```bash
./vendor/bin/sail composer analyse
./vendor/bin/sail npm run check
./vendor/bin/sail composer test:coverage
```

### PHP coverage

CI measures the backend **line coverage** (`app/`) with PCOV and blocks builds
and deploys if it drops below the configured floor (`--min=45` in
`.github/workflows/quality.yml` and in `composer.json` → `test:coverage`
script).

- To see the percentage without enforcement: `php artisan test --coverage`
- To reproduce the CI gate locally: `composer test:coverage`
- When coverage goes up, raise `--min` in both files (never lower it)

There is also a `pre-push` hook (`.githooks/pre-push`) that runs static
analysis on every push and, on pushes to `testing` / `production`, also
`composer test:coverage`. Enable it with `composer hooks:install` (or
`git config core.hooksPath .githooks`). Bypass only in an emergency with
`git push --no-verify`.

## Documentation

Keep documentation in sync with code changes. The README is a slim entry
point; detailed docs live under `docs/`.

**Rule:** if your PR changes business logic or feature behavior, update the
corresponding doc in the same PR.

### Where to document what

| Change type | Update this file |
|-------------|------------------|
| User roles, entities, permissions | `docs/business-logic.md` |
| Reminders (scheduling, dispatch) | `docs/features/reminders.md` |
| Withings sync, health data mapping | `docs/features/withings-integration.md` |
| Email, WhatsApp, CTA confirmation | `docs/features/notifications.md` |
| Audit logging | `docs/features/audit-logs.md` |
| Two-factor authentication | `docs/features/two-factor-auth.md` |
| Local setup, tests, CI, deployment, commands | `docs/development.md` |
| PR workflow, commit conventions | `CONTRIBUTING.md` (this file) |
| New doc topic or restructure | `README.md` documentation map |

Use Conventional Commit type `docs:` when a PR only updates documentation.