Contributing

Userli is free software and every contribution is welcome – code, bug reports, translations, documentation or ideas.

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. Please read the full text before participating. For reports of abusive or unacceptable behavior, contact userli@systemli.org.

Find something to work on

• Browse the issue tracker, especially good first issues.
• Report a bug or suggest a feature.
• For bigger changes, open an issue first to discuss the approach.
• Security issues: please report them privately, see SECURITY.md.

Workflow

1. Fork the repository and create a branch.
2. Set up the development environment.
3. Make your change. Follow the architecture conventions.
4. Add or update tests, see Testing.
5. Update the documentation for every audience that is affected – users, admins and operators, see Documentation.
6. If operators have to do something when updating (new or removed environment variables, migrations with manual steps, changed Dovecot configuration), describe it in UPGRADE.md.
7. Run the code quality checks (below) and open a pull request.

CI runs PHPUnit, Behat, Vitest, PHP CS Fixer, Rector, Psalm, migration checks and CodeQL on every pull request.

Coding style

Code style is enforced by PHP CS Fixer, Rector, and Psalm.

makecomposer

make lint    # check code style and Rector rules
make fix     # apply PHP CS Fixer and Rector fixes
make psalm   # static analysis

composer cs-check       # check code style
composer cs-fix         # fix code style
composer rector-check   # Rector dry-run
composer rector-fix     # apply Rector changes
composer psalm          # static analysis

For TypeScript:

yarn typecheck

Tip

Run all checks before pushing to catch issues early. CI will reject code that fails these checks.

Commits

• Use Gitmojis in commit messages, e.g. ✨ Add alias notes or 🐛 Fix voucher count
• Write commit messages in English

Database changes

Change entities in src/Entity/ and generate a migration:

bin/console doctrine:migrations:diff

Review the generated SQL. Migrations must work on MariaDB and MySQL.

Translations

User-facing text always uses translation keys. Add new keys to the English and German files, see Translations.