# Contributing

Thanks for your interest in incr. This is a small self-hosted project, issues and
pull requests are both welcome.

## Reporting issues

Use [Issues](https://forge.lvl0.xyz/lvl0/incr/issues).

For bugs, include what you expected, what happened, and enough detail to
reproduce it. `dev-logs` follows the application log.

Bear in mind what incr deliberately is: a single counter, incremented by clicking
it, with a dialog to set a value directly. Feature requests that add tracking,
history or goals are likely to be declined — a previous version had all three and
they were removed on purpose.

## Development setup

Requires PHP 8.2+ and Docker or Podman. The development environment runs in
containers defined by `docker/dev/docker-compose.yml`.

On NixOS, or anywhere with Nix installed:

```bash
git clone https://forge.lvl0.xyz/lvl0/incr.git
cd incr
nix-shell
```

The shell prints the available commands on entry and can start the containers
for you:

| Command | Description |
|---------|-------------|
| `dev-up` | Start the development environment |
| `dev-down` | Stop the development environment |
| `dev-restart` | Restart the containers |
| `dev-rebuild` | Rebuild the images |
| `dev-shell` | Enter the app container |
| `dev-artisan <cmd>` | Run an artisan command |
| `dev-composer <cmd>` | Run a composer command |
| `dev-logs` | Follow the application log |
| `dev-logs-db` | Follow the database log |

Once running:

| Service | URL |
|---------|-----|
| App | http://localhost:8000 |
| Vite | http://localhost:5173 |
| MySQL | localhost:3307 |

Without Nix, start the same containers directly from
`docker/dev/docker-compose.yml`. Contributions improving the setup instructions
for other platforms are welcome.

## Before opening a pull request

Three checks run in CI, and all three must pass. Run them locally first, from
inside the app container or anywhere the project's dependencies are available:

```bash
vendor/bin/pint --test        # code style, Laravel preset
vendor/bin/phpstan analyse    # static analysis, level 7
php artisan test              # PHPUnit, Feature suite
```

Some conventions:

- **Static analysis.** PHPStan runs at level 7 with no baseline, and the project
  is clean at that level. Keep it that way rather than introducing one. Inline
  `@phpstan-ignore` comments aren't used either.
- **Tests.** New behaviour needs a test. Tests run against sqlite in memory and
  must work offline, so use factories or fixtures rather than reaching for the
  network or a real database.
- **Dependencies.** `composer.lock` and `package-lock.json` are both committed.
  If you change dependencies, commit the updated lockfile alongside.

## Commits

One commit does one thing. Keep each commit passing all three checks so history
stays bisectable. Separate renames from behaviour changes, and mechanical edits
from logic.

Commit messages are a single line, referencing the issue they belong to:

```
52 - Replace React/Inertia with Blade + Livewire 4
```

No body, no trailers.

## License

By contributing, you agree that your contributions are licensed under the
[GNU AGPL-3.0](LICENSE), the same license as the project.