incr/CONTRIBUTING.md

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.

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:

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:

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, the same license as the project.