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

137 lines
5.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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<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! 🙏