clockula/CHANGELOG.md

# Changelog

All notable changes to Clockula are documented here.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
Tag sections feed the release notes; see [`docs/RELEASING.md`](docs/RELEASING.md).

## [Unreleased]

The first release of Clockula: alarms, timers, a stopwatch and a world clock.

### Added
- **Alarms.** Alarms are scheduled as real alarm clocks, exempt from
  battery saving and shown on the lock screen and in the status bar. They
  survive a reboot, a process kill and a change of the device's clock, and
  daylight-saving nights neither skip nor double one. If the full-screen or
  notification permission is denied, an alarm still rings, and when no sound
  can play it vibrates.
- An alarm list that shows when each alarm will ring and marks the next one.
  Changes apply as you make them, with no Save button.
- Setting an alarm, switching it on or changing its time or repeat days says
  how long until it rings, such as "Alarm set for 7 hours and 12 minutes from
  now", so an AM/PM or wrong-day slip shows at once.
- Swipe an alarm away to delete it, or use its Delete action with a screen
  reader. Deleting an alarm, or a timer from its card, doesn't ask first:
  Undo brings it back with all its settings, and a snoozed alarm comes back
  snoozed.
- Repeat days that start on your locale's first day of the week, and a "skip
  next alarm" switch so you can sleep in once without turning the alarm off.
- An "Upcoming alarm" notification two hours before an alarm rings, with a
  Dismiss button, so you can turn off today's alarm when you're already awake.
  A repeating alarm skips just that once; a one-time alarm is switched off.
  The same Dismiss shows on the alarm in the list. The notification is silent,
  and turning it off in the system settings doesn't affect the alarm.
- Schedule a one-off alarm for a date, such as a flight next Thursday, and
  pause a repeating alarm for a range of days, such as a holiday. The list
  shows "Scheduled for Wed, Oct 28" or "Paused Oct 26 – 28", and a pause ends
  on its own.
- Per-alarm sound, vibration, gradual volume, snooze length and limit, and a
  dismiss challenge (a quick sum or a two-second hold). Each one can follow the
  app default, so changing a default later still reaches it.
- Your own sounds: the device's alarm tones, the "Timer expired" sound from
  Android's own Clock, a file you pick, Silent (which still vibrates), or
  music from an app that shares its library, such as VLC or AntennaPod. If
  the music can't play, or might not be heard, the alarm rings with the
  default sound instead.
- A ring screen over the lock screen with snooze and dismiss. The dismiss
  challenge always gives you a way out, works with a screen reader, and Back
  can't silence an alarm. It also opens when the alarm or a timer goes off
  while you're using Clockula, and with "Ring screen over other apps" turned
  on it opens over any app instead of a notification.
- Choose what the volume buttons do while an alarm rings: change the volume
  (as before), snooze, dismiss or nothing. Dismiss still respects the dismiss
  challenge by snoozing instead, and a snooze press with no snoozes left
  changes the volume rather than ending the alarm. It works while the ring
  screen is showing.
- **Timers.** Run several at once, each with its own label, length and sound,
  set from a keypad with saved presets. Pause, resume, reset and +1 min work
  from the timer, from the live pill and from the notification. A finished
  timer turns the screen on and opens over the lock screen with Stop and
  +1 min. Timers keep counting through a reboot and aren't affected by changes
  to the clock.
- Timers have their own vibration switch and an optional gradual volume, both
  apart from the alarms'. A kitchen timer can just beep while alarms still
  vibrate; a silent timer still vibrates. Timer vibration starts out matching
  the alarm vibration setting, so nothing changes until you change it.
- **Stopwatch** with laps, the fastest and slowest marked, and Lap and Pause
  in the notification. It keeps counting while the app is closed.
- **World clock.** An analog face for your own time, plus cities from the
  device's time-zone database, searchable in your language. Each city shows
  the offset from your time and whether it's a different day there. Reorder
  them by dragging or with a screen reader, and set a home time zone or follow
  the device. "Display time with seconds" in Settings > Clock adds seconds to
  every time on the tab and a second hand to the face.
- An automatic local clock while travelling. When you've set a home time zone
  and your device is somewhere the time differs, the World clock tab adds a
  "Local time" row under the home face. It goes away again once you're back
  on home time, and stays hidden if one of your cities already shows that
  time. It's Google Clock's "automatic home clock" turned round: Clockula's
  face already shows home, so the clock that goes missing on a trip is the
  local one. Turn it off in Settings › Clock.
- A live pill that shows whatever is counting from every tab.
- Swipe between tabs on phones. Tablets and foldables get a side rail.
- Other apps can set, show, snooze and dismiss alarms and timers through
  Android's standard alarm intents, so assistants and automation apps work
  with Clockula. A voice-set alarm cleans up after itself once dismissed.
- Settings: theme, dynamic colour, language, and the defaults every new alarm
  and timer inherits.
- A Black theme next to Light and Dark: dark with pure black backgrounds,
  for AMOLED screens.
- Choose how long a ringing alarm or a finished timer keeps going before it
  stops on its own: 1, 5, 10, 15, 20 or 25 minutes, or Never, separately for
  alarms and timers. Ten minutes stays the default, and Never still stops
  after an hour so a phone left at home can't ring its battery flat.
- Back up alarms, timers, world clocks and settings to a JSON file, and restore
  them on this device or another one.
- "Why might my alarm not ring?", a self-check that reads your device's real
  state: permissions, battery optimisation, Do Not Disturb, alarm volume, and
  whether the system has Clockula's next alarm. It links straight to the
  setting that fixes each problem.
- **Bedtime**, under Settings: Clockula can turn on a Do Not Disturb mode of
  its own at bedtime and off at your wake-up time, on the nights you choose,
  with an optional reminder before it starts. On Android 15 and later it is a
  real mode in Settings › Modes and can also turn the screen grayscale, dim the
  wallpaper, switch to the dark theme and hide the always-on display. It needs
  Do Not Disturb access, which the screen helps you grant, and it always lets
  alarms through. It is separate from Digital Wellbeing's own Bedtime mode,
  which apps can't turn on.
- Home-screen widgets: next alarm, timer (with controls), a quick timer, and
  analog and digital clocks that show your world clocks at larger sizes. Each
  widget can follow the system theme or stay light or dark, and choose what a
  tap opens.
- **Screen saver.** A full-screen digital or analog clock with the date and
  your next alarm, for a phone on a charger or a dock. Night mode turns it
  very dim for a dark bedroom, and the clock moves a little every minute so
  nothing burns into the screen. Pick it in Android's screen saver settings,
  or open it any time from the menu on each tab. Its settings are in Settings
  → Clock and are included in backups.
- Quick Settings tiles: "Next alarm" shows the day and time of your next alarm
  and opens the Alarms tab, and "Quick timer" starts a timer with one tap,
  shows when it ends, and resets it on a second tap. Long-press the quick
  timer tile to choose its length.