docs: refine README presentation with banner and fork overview
CI Pipeline / Android Lint (push) Successful in 1m31s
CI Pipeline / Unit Tests (push) Successful in 1m6s
CI Pipeline / Build and Upload APK (push) Successful in 2m33s

This commit is contained in:
2026-10-24 12:50:05 +02:00
parent 7a21b2f8e0
commit 3670bb853e
3 changed files with 90 additions and 23 deletions
+57 -21
View File
@@ -1,11 +1,38 @@
# OpenTracks — sensor-first fork
# OpenTracks
A customized fork of OpenTracks for sport tracking that prioritizes Bluetooth sensor measurements over GPS data.
![Bluetooth sensors, recording, and activity export](docs/images/readme-banner.svg)
**Upstream:** [OpenTracksApp/OpenTracks](https://codeberg.org/OpenTracksApp/OpenTracks).
**Fork repository:** [karol/OpenTracks](https://gitea.labus.uk/karol/OpenTracks).
**A sensor-first fork of OpenTracks.** Record sport activities with Bluetooth sensors taking priority over GPS, alongside customized recording controls and audio behavior.
[Fork purpose](#fork-purpose) · [Changes from upstream](#changes-from-upstream) · [Requirements](#requirements) · [Getting started](#getting-started) · [Configuration](#configuration) · [Usage](#usage) · [Development](#development) · [Upstream maintenance](#upstream-maintenance) · [Documentation](#documentation) · [Credits](#credits) · [License](#license)
| Project | Platform | Main change | License |
| --- | --- | --- | --- |
| Personal fork | Android 8.0+ | Bluetooth sensor priority | [Apache 2.0](LICENSE) |
<p align="center">
<a href="https://gitea.labus.uk/karol/OpenTracks/releases"><strong>Download fork APKs</strong></a> ·
<a href="#getting-started">Build locally</a> ·
<a href="#changes-from-upstream">What changed</a> ·
<a href="README.upstream.md">Upstream documentation</a>
</p>
> **Fork identity** — [This repository](https://gitea.labus.uk/karol/OpenTracks) is based on [OpenTracksApp/OpenTracks](https://codeberg.org/OpenTracksApp/OpenTracks). Upstream store downloads do not include these modifications.
<details>
<summary>Browse all sections</summary>
- [Fork purpose](#fork-purpose)
- [Changes from upstream](#changes-from-upstream)
- [Requirements](#requirements)
- [Getting started](#getting-started)
- [Configuration](#configuration)
- [Usage](#usage)
- [Development](#development)
- [Upstream maintenance](#upstream-maintenance)
- [Documentation](#documentation)
- [Credits](#credits)
- [License](#license)
</details>
## Fork purpose
@@ -13,27 +40,35 @@ Use hardware sensors as the primary source of cadence, speed, and distance, with
## Changes from upstream
- Bluetooth sensor data takes priority over GPS in the modified recording flow.
- Expanded sensor settings and recording layouts.
- Media controls in the statistics view.
- Voice announcement and audio-focus changes.
- Fork-specific application IDs, including `de.dennisguse.opentracks.fork` and its build variants.
| Area | Changes maintained in this fork |
| --- | --- |
| **Recording** | Bluetooth sensor data takes priority over GPS in the modified recording flow. |
| **Interface** | Expanded sensor settings and customized recording layouts. |
| **Audio** | Media controls in the statistics view; voice announcement and audio-focus changes. |
| **App identity** | Fork-specific application IDs, including `de.dennisguse.opentracks.fork` and its variants. |
## Requirements
- Android 8.0/API 26 or later for the app, as configured in `build.gradle`.
- Android SDK with platform 37 for builds.
- The Gradle wrapper; daemon toolchain settings request JetBrains JDK 21 (`gradle/gradle-daemon-jvm.properties`).
| Use | Requirements |
| --- | --- |
| **Run the app** | Android 8.0 / API 26 or later, as configured in `build.gradle`. |
| **Build the app** | Android SDK platform 37 and the Gradle wrapper. The daemon toolchain requests JetBrains JDK 21 in `gradle/gradle-daemon-jvm.properties`. |
## Getting started
Download this fork's APKs from [Gitea releases](https://gitea.labus.uk/karol/OpenTracks/releases), or build a debug APK from the repository root:
### Install a build
Download APKs from [this fork's Gitea releases](https://gitea.labus.uk/karol/OpenTracks/releases).
### Build from source
From the repository root:
```bash
./gradlew assembleIrreproducibleDebug
```
Build output is under `build/outputs/apk/`. Store links in the inherited documentation distribute upstream OpenTracks and do not include this fork's changes.
**Output:** `build/outputs/apk/`. The debug build is intended for development.
## Configuration
@@ -66,12 +101,13 @@ After an upstream merge, review sensor priority, recording layouts, announcement
## Documentation
- [Inherited upstream README](README.upstream.md): retained from this checkout, with the local fork notice removed and malformed local links corrected.
- [Dashboard API](README_API.md).
- [Tested sensors](README_TESTED_SENSORS.md).
- [Upstream release instructions](README_RELEASE.md): review before applying to this fork.
[README style guide](docs/README-STYLE.md).
| Reference | What you will find |
| --- | --- |
| [Inherited upstream README](README.upstream.md) | Original features, screenshots, export formats, and project history. Retained from this checkout; local fork notice removed and malformed links corrected. |
| [Dashboard API](README_API.md) | Integration with external dashboards. |
| [Tested sensors](README_TESTED_SENSORS.md) | Documented sensor compatibility. |
| [Upstream release instructions](README_RELEASE.md) | Inherited release process; review before applying it to this fork. |
| [README style guide](docs/README-STYLE.md) | Shared documentation structure and presentation rules. |
## Credits