Full client for the Tdarr /api/v2 JSON API (jobs, library, nodes, stats, logs, settings, flows, multi-server switcher) plus v0.2.0 resilience: per-server timeout + slow-connection mode, retry-with-backoff on read polls, last-good-data + reconnecting chip, 60s poll backoff after repeated failures, and keep-alive eviction on app resume. Includes GPL-3.0 licensing (LICENSE/NOTICE), README, CONTRIBUTING, PREVIOUS_HISTORY, issue/PR templates, CI release-notes script, keystore docs and the vendored OpenAPI 2.0 spec.
5.1 KiB
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 on the issue tracker. Include:
- Device model and Android version
- App version (
Settings → Apps → Trafero → App infooradb 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. 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 issueorhelp wantedlabels.
2. Branch
- Branch off
main. - Use a descriptive name:
feat/node-queue-chartsfix/log-follow-scrollrefactor/json-helpers
3. Make your changes
- Follow the existing code style (Kotlin official style; Compose conventions as already used in the codebase).
- Single
:appmodule: API plumbing indata/api+data/repo, screens underui/screens/*, shared bits inui/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.mdif your change is user-visible.
4. Verify locally
./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.
5. Commit
We use Conventional Commits.
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.
- 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:
- The contribution is your own original work, or you have the right to submit it under the GPL-3.0.
- 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.
- Compose: Prefer stateless composables, hoist state, use
Modifierparameter orderingModifier.size().background().clickable(). - Imports: Wildcard imports are discouraged. Group: Android → Compose → third-party → internal.
- Naming:
PascalCasefor types,camelCasefor functions/properties,UPPER_SNAKE_CASEfor 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.versionCodeis a monotonic int and always +1 per release.
- Bump
versionCode(+1) andversionNameinapp/build.gradle.kts. - Add the
## v<VERSION> — <DATE>section toPREVIOUS_HISTORY.md. - Tag the commit:
git tag -a vX.Y.Z -m "vX.Y.Z — short summary". ./gradlew assembleDebug assembleRelease— confirm both green.- Push the tag:
git push origin vX.Y.Z— the release workflow builds, publishes the Gitea release with notes, and attaches both APKs plusTrafero-<version>-changes.md.
Thanks again for contributing! 🙏