Files
Trafero/CONTRIBUTING.md
T
nick 312858e8f6 feat: Trafero v0.2.0 - Tdarr v2 native Android client with slow-connection resilience
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.
2026-09-21 17:46:29 +12:00

5.1 KiB
Raw Permalink Blame History

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 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. 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

./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:

  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.
  • 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<VERSION> — <DATE> 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-<version>-changes.md.

Thanks again for contributing! 🙏