Development

Changes to the JournalPHP code are proposed through a pull request to github.com/ADamCarraway/journalphp.

Workflow

1. Fork the repository.
2. Set up the local environment.
3. Create a branch from master:
   • feature/short-description — a new feature
   • fix/issue-123 — a bug fix
4. Make your changes, format the code and run the tests.
5. Open a pull request against master.

Tasks and known bugs are in GitHub Issues. Before starting on a large task, discuss it in an issue.

Architecture

New code follows the project conventions: Actions, repositories with interfaces, services and DTOs. The conventions are described in Project architecture.

Code style

PHP is formatted with Laravel Pint using the configuration in pint.json:

docker compose exec app composer pint        # format
docker compose exec app composer pint:test   # check only

Vue components follow the style of the existing code in resources/js/.

Tests

docker compose exec app php artisan test

• Tests are in tests/Unit/ and tests/Feature/
• New functionality comes with tests, a bug fix comes with a test that reproduces the bug

GitHub Actions runs the tests for every push to master and every pull request to master.

Pull request requirements

• Focus: one PR solves one task
• Title: specific, for example fix: reply notification is not sent to comment author
• Issue link: Closes #123 if there is a related issue
• Description: why the change is needed and how to verify it
• Tests: new code is covered by tests, and all tests pass
• Style: composer pint:test passes without errors

Dependencies

When containers restart, Composer and npm dependencies are installed automatically if composer.lock or package-lock.json changed. To install them manually:

docker compose exec app composer install
docker compose exec frontend npm install

Background processes

After changing job or listener code, restart the queue workers:

docker compose exec app php artisan horizon:terminate

The state of the app container processes is checked with the commands in Troubleshooting.

Community guidelines

When taking part in the project, follow the Community guidelines.