Bånder
BånderDeveloper guide
On this page

Contributing

Contributions are welcome. This page covers the workflow and conventions for contributing code to Baander.

Getting Started

  1. Set up the development environment
  2. Run tests to verify everything works: make phpunit
  3. Run static analysis: make phpstan

Branch Naming

Use conventional prefixes:

Prefix Purpose Example
feat/ New feature feat/transcode-cpu-pool
fix/ Bug fix fix/auth-token-refresh
refactor/ Code restructuring refactor/party-cqrs
docs/ Documentation docs/security-guide
chore/ Maintenance chore/update-deps
test/ Test additions test/transcode-encoding

Commit Messages

Follow conventional commits with an optional scope:

feat(context): description
fix(context): description
refactor(context): description
chore(context): description
docs: description
test: description

Examples from the project's history:

feat(shared,infra): add Swoole DX overhaul — health probes, WebProfiler, Prometheus, WebSocket
fix(transcode): resolve 14 bugs in CPU process pool and encoding loop
refactor(party): replace WebSocket handler with CQRS playback commands
chore(infra): update Docker build, supervisord, FFmpeg, and email templates

Pull Request Process

  1. Create a feature branch from the default branch
  2. Make your changes with tests
  3. Run make phpunit and make phpstan — both must pass
  4. Push and open a pull request
  5. Address review feedback

Code Review Expectations

Reviewers check for:

  • DDD conventions — domain models use state objects, ports for dependencies, repositories implement domain interfaces
  • Test coverage — new behavior has tests; domain logic is tested without mocks
  • No breaking changes — API changes are additive; database migrations don't drop columns
  • Code style — matches existing patterns in the codebase

Documentation Maintenance

When you change code, update the corresponding documentation. The operator manual explains installation, routine operation, monitoring and recovery. Update the affected chapter when a change alters those tasks; keep argument and option detail in the CLI reference.

Code Change Documentation to Update
Add or modify a CLI command Use the documentation-maintainer CLI mode to update CLI Reference
Change a DDD convention Update .agents/rules/ddd-*.md, then update Coding Conventions
Add or change an environment variable Update .env.example, then update Configuration
Add or change an API endpoint Update API Reference
Add a new bounded context Update Architecture Overview and Shared Kernel
Change the build process Update Development Environment and Getting Started

Convention Synchronization

The files in .agents/rules/ are the authoritative source for coding conventions. AGENTS.md points agents to the applicable rules. When conventions change:

  1. Update the relevant rules file
  2. Regenerate coding-conventions.md from the rules files
  3. Both the rules file and the human-readable doc should reflect the same conventions

Running Tests

See the Testing page for the full test suite guide.

Read this page's source