docs: plain-language pass over every doc

Removes AI-writing patterns across the docs, store listing and
templates: dash-heavy rhythm, not-X-but-Y contrasts, one-line kickers
and decorative bold. Facts, code, links and headings are unchanged.

Also fixes leftovers copied from the sibling apps: the crash report
template promised "no calendar content", and CONTRIBUTING described
Agendula's task-provider layout, test seams and commit style.
This commit is contained in:
makiolaj committed 2026-10-06 19:14:11 +02:00
1 parent 881f6b1286
commit e870918a03
11 files changed
+697 -697

No files matched your search

+34 -34
View File
@@ -1,6 +1,6 @@
# Clockula — implementation plan
> The **design decisions and their rationale** — the "why". Locked unless
> The design decisions and their rationale (the "why"). Locked unless
> explicitly overturned here. For the moving status view see
> [`ROADMAP.md`](ROADMAP.md); for the shape of the code as it actually stands,
> [`ARCHITECTURE.md`](ARCHITECTURE.md) (written from M2 onward).
@@ -32,7 +32,7 @@ in three concrete places:
1. **The platform alarm contract.** Clockula implements `android.provider.AlarmClock`
in full (§6), so Assistant, automation apps and anything else that speaks the
standard intent vocabulary can drive it. That contract *is* the open interface
for clocks on Android — the same role `CalendarContract` plays for Calendula.
for clocks on Android, the same role `CalendarContract` plays for Calendula.
Being a good citizen of it is the thesis, applied.
2. **IANA tzdata.** World clocks are IANA zone IDs, not a bespoke city table (§5).
3. **Your data leaves whenever you want.** A documented, versioned JSON backup
@@ -44,7 +44,7 @@ Clockula owns storage, but **nothing above the data layer knows Room exists**.
The app talks to `AlarmRepository` / `TimerRepository` / `WorldClockRepository` /
`StopwatchRepository`; only the DAOs and one data source per aggregate touch Room
entities. Domain models are plain Kotlin. **Never let a Room entity or a
`@Query` string leak above the data layer** — the same discipline that let
`@Query` string leak above the data layer**. That is the same discipline that let
Agendula swap its whole storage posture without touching the UI.
---
@@ -89,7 +89,7 @@ recurrence) are a different animal from a due-date nudge.
## 3. floret-kit
Consumed as a git submodule + Gradle composite build, as the siblings do —
Consumed as a git submodule + Gradle composite build, as the siblings do:
`includeBuild("floret-kit")`, `implementation("de.jeanlucmakiola.floret:<module>")`,
with a gitignored `clockula/floret-kit/local.properties` locally and
`ANDROID_HOME` in CI.
@@ -128,7 +128,7 @@ Everything else in this app is a readout. This is the engineering.
`TIME_SET`, `TIMEZONE_CHANGED`, and `MY_PACKAGE_REPLACED`. DST transitions are
handled by this re-resolution, not by arithmetic on stored millis. A 02:30
alarm on a spring-forward night has a defined, tested behaviour.
- Scheduled with `AlarmManager.setAlarmClock()` — not `setExactAndAllowWhileIdle`.
- Scheduled with `AlarmManager.setAlarmClock()`, not `setExactAndAllowWhileIdle`.
`setAlarmClock` is the only variant the system treats as a user-visible alarm:
it is doze-exempt, and it populates `getNextAlarmClock()`, which is what draws
the status-bar alarm icon and the lockscreen line. Permission is
@@ -147,7 +147,7 @@ notification whose content intent is the ring activity.
- Full-screen intent on Android 14+ needs `USE_FULL_SCREEN_INTENT`; check
`canUseFullScreenIntent()` and deep-link to the grant screen when denied. A
denied FSI must degrade to a high-priority heads-up notification that still
rings — never to silence.
rings, never to silence.
- Gradual volume ramp, per-alarm ringtone (system `RingtoneManager` URIs, so the
user's existing sounds work), vibration pattern, `AudioAttributes` with
`USAGE_ALARM` so DND's alarm exemption applies.
@@ -162,7 +162,7 @@ notification whose content intent is the ring activity.
A "**Why might my alarm not ring?**" screen that reports actual device state, not
generic advice: exact-alarm permission, notification permission, full-screen-intent
permission, battery-optimisation exemption, **whether DND currently blocks alarms**
(read via `NotificationManager.getCurrentInterruptionFilter()` — Clockula never
(read via `NotificationManager.getCurrentInterruptionFilter()`; Clockula never
requests `ACCESS_NOTIFICATION_POLICY` or changes DND itself, it only reports what the
user already has), whether the OEM has Clockula under an aggressive app-killer, and
the next scheduled fire time as the system sees it (`getNextAlarmClock()`), compared
@@ -175,19 +175,19 @@ the exact settings page. This screen is a v1 feature, not a support afterthought
Room, schema exported and version-controlled, migrations tested from v1.
- **`alarms`** — id, hour, minute, label, enabled, repeat-day mask, ringtone URI,
- **`alarms`**: id, hour, minute, label, enabled, repeat-day mask, ringtone URI,
vibrate, snooze minutes, snooze limit, volume-ramp seconds, dismiss challenge,
`skipNextOccurrence`, timestamps.
- **`timers`** — id, label, duration, state (idle/running/paused/expired), the
- **`timers`**: id, label, duration, state (idle/running/paused/expired), the
elapsed-realtime anchor it resolves against, ringtone, sort order. Multiple
concurrent timers are first-class.
- **`world_clocks`** — id, IANA zone ID, optional custom label, sort order.
- **`stopwatch_laps`** — id, index, split, cumulative. The stopwatch's running
- **`world_clocks`**: id, IANA zone ID, optional custom label, sort order.
- **`stopwatch_laps`**: id, index, split, cumulative. The stopwatch's running
state lives in DataStore (a single record), its laps in Room so they survive
process death.
Running timers and the stopwatch anchor on **`SystemClock.elapsedRealtime()`**,
never wall-clock — a user changing the time must not warp a running timer. Alarms
never wall-clock: a user changing the time must not warp a running timer. Alarms
are the opposite: wall-clock by definition. This distinction is the single
easiest thing to get wrong in a clock app; it is tested both ways.
@@ -226,12 +226,12 @@ than writing anything. `SKIP_UI` never means "skip validation".
"timers": […], "worldClocks": […], "settings": {…} }`. The schema is **documented
in the repo** (`docs/BACKUP.md`), versioned, and import is tolerant of unknown
fields (ignored, at any level) and strict about known ones (a malformed known
field rejects the whole file — nothing is imported half-way). Ringtone URIs are
field rejects the whole file, so nothing is imported half-way). Ringtone URIs are
exported as-is with a documented fallback when the target device can't resolve
them.
Import is **whole-state replacement**, not a merge: the user is shown exactly
that before confirming. Alarm and timer records carry only configuration — ring
that before confirming. Alarm and timer records carry only configuration. Ring
state (`alarm_states`, a timer's running anchors) is never exported and never
touched by an import; an imported timer always lands `IDLE`. Record field names
mirror the Room column vocabulary (§5), so the schema, the exported Room schema
@@ -241,7 +241,7 @@ and the backup all read the same words.
## 8. Identity
Seed **`#6B7A5C`** — a muted sage/olive.
Seed **`#6B7A5C`**, a muted sage/olive.
The family's seeds are one colour rotated: Calendula `#5C6B7A` (slate blue) →
Agendula `#7A5C6B` (warm mauve) → Clockula `#6B7A5C` (sage). Same three bytes,
@@ -254,10 +254,10 @@ fallback, hand-tuned light/dark `ColorScheme`s in `ui/theme/Color.kt`.
Design principles inherited from the family (non-negotiable):
- **Expressive ≠ big or bold.** Refinement comes from shape, colour, space and
motion — never from enlarging text or upping weight.
motion, never from enlarging text or upping weight.
- Content lives **on surfaces**, not as bare text on the background.
- `MaterialShapes` / `androidx.graphics.shapes` morphs are for the genuinely
clock-specific surfaces — the analog face, the ring screen, timer progress —
clock-specific surfaces (the analog face, the ring screen, timer progress),
not sprinkled everywhere.
A clock app is mostly one enormous number. That readout is where the design
@@ -267,24 +267,24 @@ lives, and it is the thing to get right before anything else.
## 9. Navigation
Four tabs — Alarm, Timer, Stopwatch, World clock — in an M3 navigation bar, with
Four tabs (Alarm, Timer, Stopwatch, World clock) in an M3 navigation bar, with
a **live pill** floating above it whenever a timer or the stopwatch is running:
current value plus pause and stop, reachable from any tab.
This is the one deliberate departure from the stock model, and it exists because
the stock clock's worst flaw is that a running timer is invisible unless you are
standing on its tab. The pill is not decoration; it is the fix.
standing on its tab.
Adaptive: navigation rail on wide layouts, per M3 adaptive guidance.
### Home-screen widgets (M10)
Three Jetpack Glance app widgets, each a read-only mirror of state that already
exists — no widget owns data: **next alarm** (day, time, label), **timer**
exists (no widget owns data): **next alarm** (day, time, label), **timer**
(the live pill's subject timer, same selection logic, with pause/resume/reset),
and **clock** (local time, growing to world clocks at larger sizes). Tapping a
widget opens the matching tab through the same `MainActivity` intents the
`AlarmClock` contract (§6) already uses — a widget is just another caller of
`AlarmClock` contract (§6) already uses. A widget is just another caller of
that door, not a second entry point. Refresh is event-driven (`updatePeriodMillis
= 0`): widgets update when the state they mirror changes, not on a timer.
@@ -292,24 +292,24 @@ that door, not a second entry point. Refresh is event-driven (`updatePeriodMilli
## 10. Repository & pipeline
**Codeberg is canonical from the first commit** — git, issues, PRs and releases.
**Codeberg is canonical from the first commit**: git, issues, PRs and releases.
The self-hosted Gitea instance holds the secrets and runs the release job, and
push-mirrors *from* Codeberg. There is no Gitea-canonical phase to migrate out
of, which is the mistake Agendula had to unwind.
The pipeline is copied wholesale from the siblings:
- `.forgejo/workflows/ci.yaml` — contributor-facing, no secrets. Copy Agendula's,
- `.forgejo/workflows/ci.yaml`: contributor-facing, no secrets. Copy Agendula's,
adjusting `SKIP_RE`.
- `.forgejo/workflows/translations.yaml` — identical in both siblings; copy as-is.
- `.gitea/workflows/release.yaml` — **Agendula's spine** (Codeberg-canonical: pushes
- `.forgejo/workflows/translations.yaml`: identical in both siblings; copy as-is.
- `.gitea/workflows/release.yaml`: **Agendula's spine** (Codeberg-canonical: pushes
the tag to Codeberg itself, pre-1.0 prerelease flag, and the Codeberg publish
step is *not* `continue-on-error`, after five Calendula-era releases reported
green while never publishing) **plus Calendula's `play` job** grafted on
unchanged — last, isolated, `continue-on-error`, skipping cleanly until
unchanged. It runs last, isolated and `continue-on-error`, and skips cleanly until
`PLAY_SERVICE_ACCOUNT_JSON` exists. It therefore stays dormant through the
pre-1.0 run, which is the correct behaviour anyway.
- `.gitea/workflows/renovate.yml` — Agendula's, including the
- `.gitea/workflows/renovate.yml`: Agendula's, including the
`github.repository_owner == 'makiolaj'` guard.
- Issue templates, PR template, F-Droid metadata, fastlane tree.
@@ -331,8 +331,8 @@ useful reference for the parts of an alarm app that are tedious to rediscover.
- **Default posture: read it, don't copy it.** Understanding how it schedules and
how its services are wired is free; retyping our own implementation from that
understanding keeps Clockula cleanly MIT.
- **Where we genuinely lift code** — realistically only intricate scheduling or
service-lifecycle edge cases — that file keeps its Apache-2.0 header and
- **Where we genuinely lift code** (realistically only intricate scheduling or
service-lifecycle edge cases), that file keeps its Apache-2.0 header and
attribution, is listed in `docs/PROVENANCE.md`, and the Apache text ships in
`licenses/`. This is exactly the pattern Agendula already uses for the vendored
dmfs provider, so it is a known, working arrangement rather than a new risk.
@@ -348,16 +348,16 @@ DAO/repository, and the Room entity shapes as a sanity check on §5.
- Its **always-on foreground service** (`AlarmAlwaysForegroundService`). Keeping a
permanent service alive to make alarms reliable is a battery-cost workaround;
`setAlarmClock` is the supported mechanism and does not need it.
- Its **Pomodoro** feature — out of scope.
- Its **Pomodoro** feature, which is out of scope.
- Its **settings/tile component vocabulary** (`ui/components/tiles/*`,
`SettingTile`) — floret-kit's `GroupedRow` / `OptionCard` / `OptionPicker` are
`SettingTile`). floret-kit's `GroupedRow` / `OptionCard` / `OptionPicker` are
our equivalents and keep the family coherent.
- **MaterialKolor + a colour-picker dependency** — the kit's `identity` module
- **MaterialKolor + a colour-picker dependency**. The kit's `identity` module
owns theming.
- Its **no-Hilt, manual-ViewModel structure** and `minSdk 24`.
For interaction detail — snooze behaviour, the ring screen, timer presentation,
what the stopwatch does with laps — **Google Clock is the reference**, not
For interaction detail (snooze behaviour, the ring screen, timer presentation,
what the stopwatch does with laps), **Google Clock is the reference**, not
ClockMaster.
---