Contributing to TramAI

Thank you for your interest in contributing. This guide covers the essentials.

Development Environment

Prerequisites: JDK 21+ (SDKMAN recommended), Git, Gradle (use ./gradlew — no separate install needed).

git clone https://github.com/GionaGranchelli/tramAI.git
cd tramAI
java --version
./gradlew build

Building

./gradlew build                    # full build
./gradlew :tramai-core:build       # single module

Running Tests

./gradlew test                     # all tests
./gradlew :tramai-core:test        # single module

Integration tests against real providers are opt-in (set TRAMAI_RUN_*_INTEGRATION=true).

Pull Request Workflow

Fork the repo, create a branch from main.
Make your changes — include tests for new features, regression tests for bug fixes.
Run ./gradlew test to verify nothing is broken.
Open a PR with a clear title and description of the problem and approach.
Respond to review feedback.

Commit messages should follow conventional commit format: feat:, fix:, docs:, test:, refactor:, chore:.

Coding Conventions

Kotlin-first — use suspend for I/O, data classes for models, KDoc for public API.
Java-friendly — provide blocking entry points alongside Kotlin DSLs.
No hidden magic — follow the rules in AGENTS.md when present.
Tests must not require network access (use MockAiProvider and SimulatedFailureProvider).

Getting Help

Open a GitHub Issue for bug reports, feature requests, or questions. Review relevant ADRs and specs under content/engineering/ before proposing major changes.

By contributing, you agree your changes are licensed under Apache License 2.0.