98 lines
3.2 KiB
Markdown
98 lines
3.2 KiB
Markdown
|
# 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](https://forge.lvl0.xyz/lvl0/dishplanner/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:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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](LICENSE.md), the same license as the project.
|