Contributing

Thanks for your interest in DishPlanner. It's 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. Relevant log output helps; dev-logs follows the application log.

Development setup

Requires PHP 8.2+ and a container runtime (Podman or Docker). The development environment runs in containers defined by docker-compose.yml.

On NixOS, or anywhere with Nix installed:

git clone https://forge.lvl0.xyz/lvl0/dishplanner.git
cd dishplanner
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`	Full rebuild (removes volumes)
`dev-rebuild-quick`	Quick rebuild (keeps volumes)
`dev-logs [service]`	Follow logs
`dev-logs-db`	Tail database logs
`dev-shell`	Enter the app container
`dev-artisan <cmd>`	Run an artisan command
`dev-test [path]`	Run the PHPUnit suite the CI way
`dev-fix-permissions`	Fix Docker-created file permissions

Once running:

Service	URL
App	http://localhost:8000
Vite	http://localhost:5173
Mailhog	http://localhost:8025
MariaDB	localhost:3306

Without Nix, start the same containers directly from 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 --memory-limit=1G # static analysis, level 7
php -d memory_limit=512M vendor/bin/phpunit  # PHPUnit on SQLite in memory

Or run the test suite the CI way with dev-test.

Some conventions:

Static analysis. PHPStan runs at level 7 with a baseline (phpstan-baseline.neon) covering pre-existing findings. Don't add baseline entries to silence errors in code you're writing — fix the cause instead. The baseline is for cases where the analyzer or an upstream docblock is wrong, not real bugs.
Tests. New behaviour needs a test. Tests run against SQLite in memory and must not reach for the network.
Dependencies. composer.lock is committed. If you change dependencies, commit the updated lockfile alongside composer.json.

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 ticket they belong to:

45 - Add Forgejo CI workflow

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.

3.2 KiB Raw Blame History