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.
This commit is contained in:
commit
312858e8f6
50 files changed
+4446
No files matched your search
+136
@@ -0,0 +1,136 @@
|
||||
# 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! 🙏
|
||||
Reference in new issue
Block a user