# Contributing to Trafero First off, thank you for taking the time to contribute! πŸŽ‰ Trafero is a small, self-hosted-community project and every contribution β€” bug reports, documentation fixes, code β€” makes a real difference. ## How can I contribute? There are several ways you can help: ### πŸ› Reporting bugs Open a [bug report](.gitea/ISSUE_TEMPLATE/bug_report.yml) on the issue tracker. Include: - Device model and Android version - App version (`Settings β†’ Apps β†’ Trafero β†’ App info` or `adb shell dumpsys package com.trafero.app`) - Your Tdarr server version and how the phone reaches it (LAN / VPN / Wi-Fi repeater) β€” connection issues depend heavily on this - Steps to reproduce, expected vs actual behaviour - Screenshots or screen recordings if relevant ### πŸ’‘ Suggesting features Open a [feature request](.gitea/ISSUE_TEMPLATE/feature_request.yml). Before you do, check the existing issues β€” the feature you want may already be on the roadmap. Note that flow editing, node/server restart, the updater and disk-delete actions are **deliberately out of scope** (agreed safety scope β€” Trafero should never destroy media). ### πŸ”§ Submitting code changes Open a pull request. See the workflow below. --- ## Development workflow ### 1. Pick something to work on - Check existing issues for `good first issue` or `help wanted` labels. ### 2. Branch - Branch off `main`. - Use a descriptive name: - `feat/node-queue-charts` - `fix/log-follow-scroll` - `refactor/json-helpers` ### 3. Make your changes - Follow the existing code style (Kotlin official style; Compose conventions as already used in the codebase). - Single `:app` module: API plumbing in `data/api` + `data/repo`, screens under `ui/screens/*`, shared bits in `ui/common`. - **Never add calls that mutate the server** (start/stop/edit/delete) unless the issue explicitly asks for them and the safety of the call is discussed first. - Update `PREVIOUS_HISTORY.md` if your change is user-visible. ### 4. Verify locally ```bash ./gradlew assembleDebug adb install -r app/build/outputs/apk/debug/app-debug.apk ``` …then run through the affected screens against a real Tdarr server. Release builds additionally need the dev keystore β€” see [`keystore/README.md`](./keystore/README.md). ### 5. Commit We use [Conventional Commits](https://www.conventionalcommits.org/). Per-version user-facing notes live in `PREVIOUS_HISTORY.md` β€” the release CI attaches the matching section to each Gitea release automatically. Write each note (paragraph or bullet) as **one complete line β€” do not hard-wrap it**: the CI copies the section verbatim, so manual line breaks ship as premature returns, and the release UI reflows the text for you. Commit types: | Type | Use for | |------|---------| | `feat:` | new user-visible feature | | `fix:` | bug fix | | `chore:` | maintenance (deps, tooling, no user impact) | | `docs:` | documentation only | | `refactor:` | code change that neither fixes a bug nor adds a feature | | `test:` | adding or fixing tests | ### 6. Open a Pull Request - Push your branch and open a PR against `main`. - Fill out the [PR template](./.gitea/PULL_REQUEST_TEMPLATE.md). - A Gitea Actions build will run automatically β€” make sure it passes. - A maintainer will review; expect 1–2 rounds of feedback on your first PR. --- ## GPL-3.0 contribution terms Trafero is licensed under the **GNU General Public License v3.0**. By submitting a contribution, you affirm: 1. The contribution is your own original work, **or** you have the right to submit it under the GPL-3.0. 2. You agree your contribution is licensed under GPL-3.0 (or a compatible licence) and that the project may redistribute it under those terms. If you're contributing on behalf of an employer or as part of work-for-hire, please confirm you have authority to license the work under GPL-3.0 before opening the PR. --- ## Code style - **Kotlin:** [Kotlin coding conventions](https://kotlinlang.org/docs/coding-conventions.html). - **Compose:** Prefer stateless composables, hoist state, use `Modifier` parameter ordering `Modifier.size().background().clickable()`. - **Imports:** Wildcard imports are discouraged. Group: Android β†’ Compose β†’ third-party β†’ internal. - **Naming:** `PascalCase` for types, `camelCase` for functions/properties, `UPPER_SNAKE_CASE` for constants. - **Strings:** Hard-coded UI strings in the UI layer are fine for now; once translation infrastructure lands, user-visible strings must move to `strings.xml`. --- ## Release process (for maintainers) > **Version scheme:** plain semver `MAJOR.MINOR.PATCH` β€” e.g. `0.2.0`. > `versionCode` is a monotonic int and always +1 per release. 1. Bump `versionCode` (+1) and `versionName` in `app/build.gradle.kts`. 2. Add the `## v β€” ` section to `PREVIOUS_HISTORY.md`. 3. Tag the commit: `git tag -a vX.Y.Z -m "vX.Y.Z β€” short summary"`. 4. `./gradlew assembleDebug assembleRelease` β€” confirm both green. 5. Push the tag: `git push origin vX.Y.Z` β€” the release workflow builds, publishes the Gitea release with notes, and attaches both APKs plus `Trafero--changes.md`. Thanks again for contributing! πŸ™