diff --git a/README.md b/README.md index d3f5776..5344e43 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,132 @@
Clockula is the clock sibling to [Calendula](https://codeberg.org/jlmakiola/calendula) (calendar) and [Agendula](https://codeberg.org/jlmakiola/agendula) (tasks). The -name follows theirs: *clock*, given Calendula's `-ula` ending. A Calendula flower +name follows theirs: *clock* with Calendula's `-ula` ending. A Calendula flower head is botanically a cluster of many small *florets*, so the three apps are -florets of one bloom โ and they share one, [floret-kit](https://codeberg.org/jlmakiola/floret-kit). +florets of one bloom. They share one library, +[floret-kit](https://codeberg.org/jlmakiola/floret-kit). -> ๐ง **Early development.** The spec is locked; the app is being built. See -> [`docs/ROADMAP.md`](docs/ROADMAP.md) for where it actually is. +1.0.0 is in its last betas before the stable release. -## The honest difference from its siblings +## Features -Calendula is a pure front-end over Android's `CalendarContract`. Agendula speaks -the dmfs `TaskContract`. Both put a good interface on a standard someone else -already maintains. +### Alarms -**There is no open provider behind a clock.** Alarms, timers and laps are -Clockula's own data, so Clockula is the first app in the family to own its -storage โ by design, not as a fallback. What that commitment is replaced with is -the first section of [`docs/PLAN.md`](docs/PLAN.md), and it comes down to three -things: +- Repeat schedules, snooze, your own ringtones and per-alarm settings +- Scheduled as real alarm clocks: exempt from Doze, and shown on the lock + screen and in the status bar +- Re-resolved against your current time zone whenever it changes, so DST and + travel don't shift them +- A self-check screen that reads your device's actual settings. If one of them + would stop an alarm ringing, Clockula names it and opens that settings page, + instead of failing quietly at 7am. -- **Clockula speaks Android's standard alarm contract.** It implements - `android.provider.AlarmClock` in full, so your assistant and your automation - apps can set alarms and timers in it exactly as they would in any stock clock, - and the system status bar and lock screen show its next alarm. -- **World clocks are IANA time zones**, not a bespoke city list that goes stale. -- **Your data exports** to a documented, versioned JSON file whenever you want - it, because data you can't take with you isn't really yours. +### Timers, stopwatch and world clock -## Alarms that actually ring +- Several timers at once, controllable from the notification shade +- A stopwatch with laps +- World clocks from the IANA time-zone database built into Android, so the + city list doesn't go stale +- A running timer or stopwatch stays reachable from every tab -An alarm app is only worth having if you can trust it, so Clockula treats that as -the feature rather than the plumbing. Alarms are scheduled as real alarm clocks โ -doze-exempt, visible to the system โ and re-resolved against your current time -zone whenever anything moves underneath them, so DST and travel don't silently -shift them. +### Widgets -When something on your device *would* stop an alarm ringing, Clockula tells you -which setting it is and takes you there, instead of failing quietly at 7am. +- Three home-screen widgets: next alarm, timer and clock +- Each widget picks its own theme, or takes its colours from your wallpaper -## Documentation +### Works with other apps -Start with [`docs/`](docs/): [`PLAN.md`](docs/PLAN.md) is the spec and the -reasoning, [`ROADMAP.md`](docs/ROADMAP.md) is the status, -[`ARCHITECTURE.md`](docs/ARCHITECTURE.md) is how the code is put together, and -[`RELEASING.md`](docs/RELEASING.md) is the release runbook. +- Clockula implements Android's standard `AlarmClock` intents in full. Your + voice assistant and automation apps can set alarms and timers in it the same + way they would in the stock clock. +- Alarms, timers, world clocks and settings export to a JSON file whose format + is documented in [`docs/BACKUP.md`](docs/BACKUP.md), and import back from it. -## Building +### Design and privacy + +- Material 3 Expressive throughout, with dynamic colour on Android 12+, light + and dark themes, and expressive motion and shapes +- A per-app language setting. Clockula ships in English for now; + [help translate](#translations). +- No telemetry, no analytics and no internet permission + +## Where your data lives + +Calendula works on top of Android's `CalendarContract`, and Agendula can work on +top of the dmfs `TaskContract`. Both put an interface on a standard someone else +maintains. Clocks have no such provider, so Clockula keeps alarms, timers and +laps in its own database, the first app in the family to do so. The first +section of [`docs/PLAN.md`](docs/PLAN.md) explains how it makes up for the +missing standard: the `AlarmClock` intents, IANA time zones and the documented +backup format listed above. + +## Install + +| Channel | Available | Notes | +| --- | --- | --- | +| [Codeberg release / Obtainium](#codeberg-release--obtainium) | Now, as betas | Plain APK download, or automatic with Obtainium | +| [Self-hosted F-Droid repo](#self-hosted-f-droid-repo) | From 1.0.0 | Add the repo once | +| [Build from source](#build-from-source) | Now | Full control | + +### Codeberg release / Obtainium + +Every release is on +[Codeberg](https://codeberg.org/jlmakiola/clockula/releases) with the signed +APK and a `.sha256` checksum. Betas are published as pre-releases. Download the +APK and install it directly. + +For automatic updates, use [Obtainium](https://github.com/ImranR98/Obtainium). +On your phone, +[add Clockula in one tap](https://apps.obtainium.imranr.dev/redirect?r=obtainium://add/https://codeberg.org/jlmakiola/clockula), +or add it by hand: *Add App*, paste `https://codeberg.org/jlmakiola/clockula`, +then *Add*. While Clockula is in beta, switch on *Include prereleases* for it, +or Obtainium won't find anything. A beta updates in place to later betas and to +the stable release. + +### Self-hosted F-Droid repo + +From the stable 1.0.0 on, every release is also published to the self-hosted +F-Droid repository that serves Calendula and Agendula. If you already have it, +Clockula will show up there. Otherwise add it once: + +1. In your F-Droid client, open *Settings โ Repositories โ Add* (or open the + link below on your phone): + + ``` + https://apps.dev.jeanlucmakiola.de/dev/fdroid/repo?fingerprint=C2C0640402BF458FC0ED957AF0B37AA4C14022E72F89CE90B5965B458CF73425 + ``` + + Repo: `https://apps.dev.jeanlucmakiola.de/dev/fdroid/repo` ยท + fingerprint (SHA-256): + `C2C0 6404 02BF 458F C0ED 957A F0B3 7AA4 C140 22E7 2F89 CE90 B596 5B45 8CF7 3425` + +2. Refresh, search for Clockula and install it. + +### Build from source ```sh git clone --recurse-submodules https://codeberg.org/jlmakiola/clockula.git @@ -69,10 +135,53 @@ cd clockula ``` floret-kit is a submodule built from source as a Gradle composite build, so -`--recurse-submodules` is not optional. The included build needs to find the -Android SDK on its own: either export `ANDROID_HOME`, or drop a `sdk.dir=โฆ` line -in a (gitignored) `floret-kit/local.properties`. +`--recurse-submodules` is required. The included build has to find the Android +SDK on its own: either export `ANDROID_HOME`, or put a `sdk.dir=โฆ` line in a +(gitignored) `floret-kit/local.properties`. [CONTRIBUTING.md](CONTRIBUTING.md) +covers tests and lint. + +The F-Droid repo and the Codeberg releases share the same signing key, so +you can switch between them without reinstalling. + +## Documentation + +- [Contributing](CONTRIBUTING.md): the workflow, the build and the + architectural rule changes are reviewed against +- [Plan](docs/PLAN.md): the spec and the reasoning behind it +- [Roadmap](docs/ROADMAP.md): what has shipped and what's next +- [Architecture](docs/ARCHITECTURE.md): how the code is put together +- [Backup format](docs/BACKUP.md): the JSON export schema +- [Releasing](docs/RELEASING.md): the release runbook +- [Privacy policy](docs/PRIVACY.md): the source of the page at + [jeanlucmakiola.de/clockula/privacy](https://jeanlucmakiola.de/clockula/privacy) + +## Contributing + +Bug reports, ideas and patches are welcome on +[Codeberg](https://codeberg.org/jlmakiola/clockula/issues). Translations go +through [Weblate](#translations), not pull requests. Read +[CONTRIBUTING.md](CONTRIBUTING.md) before writing code. + +## Translations + +Clockula is written in English. Translations are managed on a self-hosted +Weblate, and partial ones are fine: untranslated strings fall back to English. + +[Help translate Clockula](https://weblate.dev.jeanlucmakiola.de/engage/clockula/) + +You don't need to code. Register on the Weblate server, pick a language (or +request one) and translate in your browser. + +## Privacy + +Clockula has no analytics, tracking, ads, crash-reporting SDK or third-party +services. It doesn't have the internet permission, so it can't send anything +anywhere. Your alarms, timers and world clocks stay in the app's private +storage on your device. + +[Privacy policy](https://jeanlucmakiola.de/clockula/privacy), written in +[`docs/PRIVACY.md`](docs/PRIVACY.md), which is what that page renders. ## Licence -MIT โ see [`LICENSE`](LICENSE). +[MIT](LICENSE), Jean-Luc Makiola, 2026