#Contributing

#Code Conventions

#Language

• GraalVM JDK 21 source/target
• Use modern Java features (records, sealed classes, pattern matching where appropriate)
• Public-facing identifiers and REST contracts are in English
• Code comments may be in English or Chinese

#Lombok

• Use @Data, @Getter, @Setter for DTOs and entities
• Exception: Entities with @Id that go through CrudRepository.update() must use explicit getters/setters
• Use @Slf4j for logging

#Controllers

• Annotate with @Controller("/_matrix/...")
• Use @Secured(SecurityRule.IS_ANONYMOUS) for Matrix compatibility (most endpoints)
• Use @Secured(SecurityRule.IS_AUTHENTICATED) only for admin-only endpoints
• Return proper Matrix error responses via BaseException and BaseErrorEnum
• Avoid returning bare HttpResponse.ok() or HttpResponse.serverError() without a body

#Services

• Prefer constructor injection over field injection
• Throw BaseException for domain errors (handled by MatrixExceptionHandler)
• Use @Inject for dependency injection

#Repositories

• Extend Micronaut Data interfaces
• Annotate with @JdbcRepository(dialect = Dialect.H2)
• Follow Micronaut Data naming conventions for query derivation

#Entities

• Use @MappedEntity with explicit table names
• Use @Id for primary keys
• Avoid Lombok @Getter/@Setter on entities with CrudRepository CRUD operations

#Error Handling

• Define error codes in BaseErrorEnum
• Throw BaseException for business logic errors
• MatrixExceptionHandler converts exceptions to Matrix error format

#Commit Messages

Follow conventional commits:

feat(p5): implement federation core compliance (FED-01~06)
fix(e2ee): add event_id to to-device events in sync response
docs: update STATUS.md with verification results
test: add P5 federation integration tests

#Pull Requests

1. Create a feature branch from main
2. Implement changes with tests
3. Run mvn test — all tests must pass
4. Update docs/plan/STATUS.md if adding new features
5. Submit PR with clear description of changes

#Running Locally

mvn compile        # Compile
mvn test           # Run tests
mvn exec:java      # Start server

#Project Status

All phases P0–P5 are complete. See Roadmap for details.