Contributing

Contributing

Conventions and workflow for contributing to THD Room Finder.

Getting Started

1. Fork the repository on GitHub
2. Clone your fork: git clone --recurse-submodules https://github.com/arudaev/THD-Room-Finder.git
3. Build the project (see Building and Deploying)
4. Create a feature branch and start coding

Branch Naming

Prefix	Use case	Example
feature/	New features	feature/favorites-screen
fix/	Bug fixes	fix/crash-on-empty-periods
refactor/	Code restructuring	refactor/repository-flow

Commit Messages

• Imperative mood — "Add room list screen", not "Added room list screen"
• Under 72 characters for the subject line
• One logical change per commit — don't mix features with refactors
• Add a blank line and longer body for complex changes

Add room list screen with building filter

Implements the main browse screen. Filtering is client-side to avoid
redundant API calls when switching between buildings.

Code Style

Kotlin

• Follow the Kotlin coding conventions
• No wildcard imports
• Trailing commas on multi-line parameter lists
• Use internal visibility for module-scoped symbols

Swift

• Follow the Swift API Design Guidelines
• No force-unwrapping (!) outside of test code
• Prefer async/await over completion handlers

Compose

• State hoisting: screens receive state + lambdas, not ViewModels directly
• Use remember and derivedStateOf to minimise recomposition

Naming Conventions

Kind	Pattern	Example
Android screen	<Feature>Screen	HomeScreen
Android ViewModel	<Feature>ViewModel	HomeViewModel
Repository interface	<Entity>Repository	RoomRepository
Repository impl	<Entity>RepositoryImpl	RoomRepositoryImpl
Use case	<Action><Entity>UseCase	GetFreeRoomsUseCase
DTO	<Entity>Dto	PeriodDto
DB entity	<Entity>Entity	RoomEntity
Hilt module	<Scope>Module	NetworkModule
iOS View	<Feature>View	RoomDetailView

Architecture Rules

1. Respect layer boundaries — UI → Domain ← Data. Domain has no Android or iOS framework imports.
2. Don't introduce new dependencies without discussion — the tech stack is intentional and minimal.
3. Error handling — repositories return Result<T> (Android) or throws (iOS). Never crash on bad API responses.
4. Defensive parsing — DTOs use ignoreUnknownKeys = true and nullable fields.

Testing

• Write unit tests for ViewModels, use cases, and repositories
• Use fakes over mocks (see FakeRoomRepository in the Android test directory)
• Name tests descriptively: fun `shows error when repository fails`()
• Run the full suite before submitting a PR:

./gradlew test lint

Pull Request Process

1. Ensure ./gradlew assembleDebug test lint passes
2. Keep PRs focused — one logical change per PR
3. Write a clear description: what changed and why
4. Link any relevant issues

Releasing

Releases are fully automated. To cut a release:

git tag v1.2.3
git push origin v1.2.3

The release workflow builds, signs, and publishes the APK to GitHub Releases, and uploads a beta to TestFlight if Apple credentials are configured. See CI and Delivery for the full pipeline and required secrets.