From 3670bb853ed4c6ba2179e7cfbb1a5f180ee49eda Mon Sep 17 00:00:00 2001 From: karol Date: Sat, 24 Oct 2026 12:50:05 +0200 Subject: [PATCH] docs: refine README presentation with banner and fork overview --- README.md | 78 +++++++++++++++++++++++++---------- docs/README-STYLE.md | 20 ++++++++- docs/images/readme-banner.svg | 15 +++++++ 3 files changed, 90 insertions(+), 23 deletions(-) create mode 100644 docs/images/readme-banner.svg diff --git a/README.md b/README.md index 4b0b1c39a..b960d52c3 100644 --- a/README.md +++ b/README.md @@ -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) | + +

+ Download fork APKs · + Build locally · + What changed · + Upstream documentation +

+ +> **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. + +
+Browse all sections + +- [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) + +
## 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 diff --git a/docs/README-STYLE.md b/docs/README-STYLE.md index 79c27b12d..265152371 100644 --- a/docs/README-STYLE.md +++ b/docs/README-STYLE.md @@ -1,12 +1,12 @@ # Repository README standard -Version: 1.0. Documentation language: English. +Version: 1.1. Documentation language: English. A README should explain the project, help a new reader start it, and point to detailed references. Keep project-specific instructions and existing attribution when applying this standard. ## Original projects -Start with one `# Project name` heading and a short description of what the project does and who it serves. An optional local screenshot or banner may follow. Then add a navigation line linking to the level-two sections present in the document. +Start with one `# Project name` heading and a short description of what the project does and who it serves. An optional local screenshot or banner may follow. Follow with a compact project facts table and three or four primary navigation links. Put the complete section navigation inside a `Browse all sections` disclosure. Use these level-two headings in this order. Omit sections that do not apply; do not add empty sections or filler just to match the template. @@ -69,6 +69,22 @@ Borrowing a component or taking inspiration from another project does not by its - Preserve existing technical instructions, screenshots, credits, and license notices when reorganizing. Move long references into `docs/` when useful and update links relative to their new location. - Never infer a license from a badge, framework, dependency, or a different repository. License choices require an explicit project decision. +## Presentation + +Use the same visual hierarchy for original projects and forks: + +1. A plain H1 with the project name. +2. An optional repository-local SVG banner or real product screenshot, with meaningful alt text. Use a short, factual tagline and a simple product-specific illustration. Keep text readable at narrow widths, and preserve an existing project logo or identity. +3. A one-paragraph description with a bold opening sentence. +4. A compact facts table with one row and three or four columns, such as project type, platform, deployment, storage, or license. Include only verified facts. +5. Three or four primary action links, optionally centered with `

`. Use real destinations such as Getting started, Releases, Configuration, and Usage. Do not imply a download exists unless one is available. +6. A short fork-identity callout for forks, linking to both this repository and upstream and distinguishing their downloads. +7. A `

` block labeled `Browse all sections` with links to every level-two section. + +Use short two- or three-column tables for grouped capabilities, station/platform support, fork changes, and documentation links. Keep ordinary prose for explanations. Put long file trees, diagnostic references, and platform-specific details in `
` blocks with descriptive summaries. Leave installation prerequisites, required configuration, important limitations, and primary commands expanded. Include blank lines around Markdown inside HTML disclosure blocks so Gitea renders it correctly. + +Keep the header compact. Banners should use repository-local assets and render without scripts, external fonts, or network dependencies. Do not add decorative status badges or unverified build/test claims. A banner is optional for small repositories; the facts table, clear primary links, and content hierarchy should still work without one. + ## Maintenance Update the README alongside changes to installation, configuration, commands, supported hardware, or release behavior. Check local links, navigation, and Markdown structure before committing. Run a command only when its effects are appropriate; a documentation check must not flash hardware, publish a release, send messages, or start an import. diff --git a/docs/images/readme-banner.svg b/docs/images/readme-banner.svg new file mode 100644 index 000000000..81d2745c4 --- /dev/null +++ b/docs/images/readme-banner.svg @@ -0,0 +1,15 @@ + +Bluetooth-first activity tracking +Hardware sensors at the heart of your recording. + + + + + +OPENTRACKS / ANDROID FORK +Bluetooth-first activity tracking +Hardware sensors at the heart of your recording. +PERSONAL FORK / KAROL LABUS +SensorsSpeed / cadenceRecordingSensor priorityExportGPX / KML / KMZ + +