v0.23.0: Routine, first public version

This commit is contained in:
2026-11-15 02:22:09 -08:00
commit 5ea848bddc
285 changed files with 23886 additions and 0 deletions
+326
View File
@@ -0,0 +1,326 @@
# Routine
![Routine with the template routine it starts with](docs/screenshot.png)
The day's routine as one long list you tick off as you go. Blocks (Morning, Work, Evening, …) hold
your tasks and their sub-tasks; tick them as you do them, skip what isn't happening today, and
write a line about the day at the bottom. Every tick plays a little stop-motion animation, with
its own sound, out of the box you ticked. Streaks count the days in a row a task got done, and
three windows look back: **History** (every task, every day, as a grid), **Statistics** and the
**Journal** (your notes).
For Linux and macOS. There is also an app for the Rabbit R1, kept in step with the desktop through
a small sync server of your own (Linux only for now).
## Install
**macOS** (13 Ventura or newer, Apple silicon or Intel). Open Terminal (⌘ Space, type Terminal),
paste this line and press Return:
```
curl -fsSL https://git.autonomic.zone/trav/routine/raw/branch/main/install-mac.sh | bash
```
No password, Xcode or Homebrew needed: it downloads Routine, its own Python and Qt (about 400 MB,
all kept in `~/Library/Application Support/Routine-app`) and puts **Routine** in your Applications
folder, so it's in Launchpad and Spotlight. To keep it in the Dock: open it, right-click its Dock
icon → Options → Keep in Dock. *The Mac version is new and hasn't been tried on a real Mac yet: if
something's off, see [If something goes wrong](#if-something-goes-wrong).*
**Linux** (Fedora, Ubuntu / Debian, Arch, and most others). In a terminal:
```
curl -fsSL https://git.autonomic.zone/trav/routine/raw/branch/main/install-linux.sh | bash
```
It needs Python 3.10 or newer (every current distribution has it) and PySide6 (Qt for Python). If
your system has PySide6 already, that's used; if not, it offers your distribution's package (it
shows the `sudo` command and asks first) or a private copy just for Routine (about 250 MB, no
password). The app goes to `~/.local/share/routine-app`, and Routine appears among your apps.
**Update**: run the same line again. **Uninstall**: the same line with `-s -- --uninstall` on the end
(`… | bash -s -- --uninstall`). Neither ever touches your routine or your history.
## First steps
1. **Open Routine.** The first time, it starts from a template routine: a few blocks with tasks
that show what a routine can hold (sub-tasks, a weekend-only block, a weekday-only task, a
suggestion, a calm task). Have a look, tick something.
2. **Make it yours**: Settings (Ctrl+, on Linux, ⌘, on a Mac) → **Routine**. Delete the template's
tasks, add your own blocks and tasks, give them hours, colours and days, then **Save routine**.
See [Changing the routine](#changing-the-routine).
3. **Tick as you go.** The window opens on the block you're in now (») and the day rolls over at 4 am,
so late-night tasks count for the evening before. Scroll sideways (or ‹ ›) for earlier days.
4. **Streaks** build by themselves; **View → History / Statistics / Journal** look back over them
([Streaks](#streaks)).
5. **Back it up**: your whole routine and history are two files; see [Your data](#your-data).
## On a Mac
Everything on the desktop works the same, with a Mac's habits: the menu bar is at the top of the
screen, ⌘ stands in for Ctrl in every shortcut (History is ⌘Y, since ⌘H hides an app), Settings
is in the Routine menu, and windows have the usual title bar. **Coming soon on macOS**: the sync
server and the Rabbit R1 (their Settings pages are there, greyed out). Your data is kept in
`~/Library/Application Support/Routine`, the error log in `~/Library/Logs/Routine`.
## If something goes wrong
Routine keeps running after most errors: it writes what went wrong to a log and says so once.
**Help → Open log folder** shows the log (`errors.log`; `launch.log` has the messages from the last
start). The log holds only where in the program things went wrong, never your routine or notes.
Please send it along with what you were doing. **Help → About Routine** shows the version and where
everything is kept.
- Linux: `~/.local/state/routine/`
- macOS: `~/Library/Logs/Routine/`
## The animations
Every tick plays a little stop-motion animation, with its own sound,
out of the box you ticked. The more you tick in a day, the more of them you get to see: the
first 5 ticks draw from set 0 (the biggest, 40 animations, since those ticks happen every day),
the next 5 from set 1, and so on, purely at random within the set: repeats can happen, and
nothing remembers what has played (`shared/ANIMATIONS.md` lists them all). A task marked
**calm animation** in the editor plays one of 40 calm ones instead: slower, two seconds, with
quiet sounds, for early mornings and late nights. Each one starts at the box you ticked but is moved,
as little as it takes, to stay entirely on screen (and drawn smaller only if it couldn't fit at all). It still counts toward the next set. Once you're past the last set, a special two-second star plays too: time to ask for
more animations.
## Using it
- **One day, top to bottom**: blocks (Morning, Work, Lunch, …) with every task and sub-task as a
checkbox. Ticking or skipping a task does the same to its sub-tasks that are still open.
- **skip** hides a task without ticking it off (recorded as skipped, no animation).
- **Click (tap on the R1) a block's heading** to hide its tasks, again to show them; remembered
per device. Until you've done it once, each heading says "click/tap to hide" or "to show".
- **All / Incomplete / Completed** at the bottom (All / To do / Done on the R1, to fit):
everything, only what's still to do, or only what got ticked (with the tasks it sits under).
In All you can untick a done task or unskip a skipped one. Today remembers the last pick; an
earlier day always opens on Completed.
- **Ticking a task on an earlier day** asks first ("this is for a day in the past, …"): yes / oops.
- **»** (Now) jumps to today at the current time (the latest block that has started: after the
last block, until the day rolls over, that last one); the app opens there. The date at the top
and the note at the bottom stay put while the tasks scroll between them.
- **Earlier days are to the left**: scroll sideways (touchpad), Alt+Left / Alt+Right, or ‹ ›.
- **The note** at the bottom of each day, past days included.
- **Settings → Appearance → Look**: the date (always "Sunday, November 8th"; **Show the year** adds ", 2026",
and the R1 follows at install), the header font (the date; default Edition), the note title's
font (default Caveat, a handwritten script bundled in `shared/fonts`, SIL Open Font License), and
block colours: a swatch by each block's name, the heading row in its colour, or the whole block.
**Emboss the block colours** draws whichever of those as a button (hover and press darken it,
as on any button), with no dark edge unless **Colours → Block edge** gives it one (0 % none,
35 % a button's); the R1 stays flat.
**Say "now" on the current block** (on by default) shows or hides that word; the R1 never says it.
- **Settings → Appearance → Colours**: every gray (header, background, tasks area, buttons, the note,
lists) and a tint, with Light and Dark tabs for each mode's own set (shared-resources design.html#colors).
- The day rolls over at 4 am (`dayStartsAt`), so night tasks after midnight count for the night before.
- **Ctrl+,** (or Edit → Settings in the menu bar: tap **Alt** to show it) opens Settings: the
routine editor, look, sounds, tooltips, streaks (streak animations, cheat days, embossed history
dots), where the data is kept, the sync server, the R1. On a Mac: **⌘,** or Routine → Settings
in the menu bar at the top of the screen.
- **Help → Open log folder** and **Help → About Routine** (the version, and where everything is kept).
- On the R1 the wheel stays volume (wheel down + side button = screenshot); scroll by touch.
The moon / sun in its bottom bar switches between the dark look (white on black, best in
bright sunlight) and the light one (the desktop's: embossed boxes, the Edition date, the
desktop's block colouring, sent along at install). The date scrolls away with the tasks there.
## Changing the routine
Settings → Routine: a tree of blocks and the tasks nested under them, with a form for the
selected one (name, hours, colour and days of the week for a block; name and days for a task,
and whether it's **just a suggestion**: quiet text with no checkbox, like an idea for how to do
the task above it, never ticked or skipped) or has a **calm animation** (see below). A block or
task left off a day takes everything under it along. ↑ at the top of a block moves a task into
the end of the block above; ↓ at the bottom moves it into the start of the block below. Add block / task /
sub-task, delete, move with ↑ ↓, and indent/outdent with → ←. **Save routine** bumps its `rev`,
gives today's list the new routine, and sends it through the sync server to the R1 at its next sync. Past
days keep the routine they had; renaming a task keeps its history (moving it under a different
parent starts a new one).
**The first run** starts from a template (`shared/schedule.json`): a few blocks whose tasks show
what a routine can hold (sub-tasks two deep, a weekend-only block, a weekday-only task, a
suggestion, a calm task). It's copied into your data folder as `schedule.json`, and from then on
that copy is your routine: it always wins over the template, whatever their `rev`s. Delete the
template's tasks in Settings → Routine and add your own. A fresh R1 install also begins with the
template (its `rev` is 0, so the first sync replaces it with the desktop's routine as soon as
that has been saved once).
An install from before the template (a history already there, but no `schedule.json` of its
own) is never switched to the template: it takes a `schedule.from-repo*.json` from the data
folder if there is one (a saved copy of the routine the repo used to ship), else it rebuilds the
routine from the most recent day in the history (that day's blocks and tasks, ids kept; weekday
limits can't be told from one day, so check them in the editor).
## Streaks
Every task keeps a streak: the days in a row it got ticked. Days a task isn't on (a weekday-only
task at the weekend) don't count either way, and today doesn't count against it until it's over.
When a tick by hand brings a streak to **7, 21, 42, 66, 100, 150, 254 or 365** days (and every 100
more after that), a special two-second streak animation plays instead, showing the number (a calm
task gets a calm one). **Cheat days**: after 7 days in a row (Settings → Streaks sets how many, or
turns it off) one missed day is forgiven and the streak carries on; two misses running end it.
**On the R1** the same ticks play the same streak animations, with the same number: the R1 only
holds the last couple of months, so the desktop sends each streak as it stood 30 days ago through
the sync server (with the streak settings), and the R1 counts on from there. Until it has that (a
server that hasn't been updated yet), the R1 counts from its own days and only plays a streak animation when it
can see where the streak began; the settings then come along at install.
**View → History** (Ctrl+H; ⌘Y on a Mac), **Statistics** (Ctrl+T) and **Journal** (Ctrl+J) open windows of their own
beside the main one, each showing a range of days picked at its top (last 30 / 90 days, this
year, all time, or from – to).
**History** is the range as a grid: blocks and their tasks across the top, days down the left
(months marked by a line), opening on today at the bottom. Two buttons beside the range tiles
change that, both remembered: the arrow flips the day order (newest at the bottom or at the top;
with the axes swapped, on the right or on the left), and the axes button (lit while on) swaps the
axes: days across, tasks down the side, so long streaks run sideways on a wide screen. A day a
task got done is a dot in its block's colour; a streak joins its dots into one pill, which narrows
to a thin stem over days the task wasn't on, so a weekday-only streak reads as one. A cheat day is
a hole in the pill; a missed day a faint speck; today, still to do, a faint ring. Click a block's
heading to fold it into one column (or row): full colour where every task was done, pale where
some were, empty where none were (click again to open it; remembered). Hover a dot for the task,
the day and its streak; hover a heading for the task's full name. Pinch, Ctrl+wheel or Ctrl + / −
zoom around the pointer (Ctrl+0 back to 100 %, remembered); zoomed far out it turns into bars with
week or month labels, so years fit. Home / End jump to the start / end of the days (top or left /
bottom or right). Settings → Streaks embosses the dots or draws them flat.
**Statistics** lays the routine out as the main window does (the same blocks, colours and indents,
every task with a record in the range, in today's order; a task since removed in quiet italics),
read-only, with a figure where the checkbox would be. The tiles at the bottom pick it: **% of days**
(of the days it was on), **Longest streak** (in the range, with the cheat days that streak used and
the streak going now beside it) or **Days done**; each heading shows its tasks' % together.
Click a task for its details in the panel at the bottom (longest streak with its dates and cheat
days, the streak now, % and days done, the next reward and how far off it is); click it again and
the panel sums up the range (the routine's %, the best streaks, perfect days, cheat days used).
Headings hide their tasks on a click here too, remembered apart from the main window's.
**Journal** is the notes, newest first, each under its date with the % of that day's tasks done;
click the % for what got done that day, by block, and below a line what didn't. **With a note**
(the default) leaves out the days without one; **Every day** shows them too. Double-click an entry
to open that day in the main window; right-click to copy its note.
## Your data
Two files are everything: **`schedule.json`**, your routine, and **`routine.db`**, the history:
every day from the first run on has a record, ticked or not (SQLite, one JSON document per day:
see `routine/model.py`), with your notes and a log of every animation that played, when, and for
which task. The sync server only relays the last 60 days between the desktop and the R1.
They start out in
- Linux: `~/.local/share/routine/` (settings in `~/.config/routine/config.json`)
- macOS: `~/Library/Application Support/Routine/` (settings in `config.json` there too)
To **back them up**, copy those two files (with Routine closed, to be safe), or keep them in a
folder that's backed up or synced already: **Settings → Data** keeps either one in a folder of
your choosing. Pick it and the file is moved there (copied, checked, then the original removed).
If that folder already has one, it asks: **use that one** (yours stays where it was), **replace
it with mine** (that one is kept beside it as `<name>.replaced-<time>`), or cancel. **Default**
moves it back. All of it happens with the app running: the open windows and the sync carry on.
The folders are `schedule_dir` and `db_dir` in `config.json` (empty = the default).
`ROUTINE_HOME=DIR` puts the data, the config file and the logs in DIR instead, for testing.
Uninstalling or updating Routine never touches these files.
## Licence
Routine is under the [PolyForm Noncommercial License 1.0.0](LICENSE): you're free to use it, change
it and share it for any noncommercial purpose; commercial rights are reserved by the author.
Required Notice: Copyright trav (https://git.autonomic.zone/trav/routine)
The bundled Caveat font (`shared/fonts`) is under the SIL Open Font License (`shared/fonts/Caveat-OFL.txt`).
Qt for Python (PySide6) is under the LGPL.
---
# For developers
```
python3 -m routine # run it from a checkout (needs PySide6, or PyQt6)
scripts/install-desktop.sh # put this checkout in the app grid (Linux); then right-click → Pin to Dash
./install-linux.sh # or: a copy of its own in ~/.local/share/routine-app (re-run to update)
```
**Qt**: everything imports Qt through `routine/qt/` (`from routine.qt.QtCore import Qt, Signal`),
which picks PySide6 when it's there and falls back to PyQt6; `ROUTINE_QT=pyside6|pyqt6` forces
one. The installers use PySide6 (LGPL), pinned in `install-*.sh` and `scripts/build-mac-app.sh`.
One PySide6 pitfall: an attribute named like a Qt virtual method (`self.metric = …` on a QWidget)
shadows it and crashes PySide6 when Qt calls it.
**Linux and macOS**: what differs lives in `routine/system.py` (data / config / log folders, the
system or the app's own window frame, the global menu bar, sync and the R1 off on a Mac, sound
players, gsettings, shortcuts), each function testable for either platform from either
(`tests/test_system.py`). On a Mac the windows keep the system's frame (Qt can't resize a frameless
window there), the menu bar is the Mac's, and sync / the R1 are "coming soon".
**The Mac app**: `install-mac.sh` makes a small Routine.app that starts the app from
`~/Library/Application Support/Routine-app` (uv, a standalone Python and PySide6, all inside that
folder). `scripts/build-mac-app.sh`, run on a Mac, makes a self-contained, ad-hoc signed
Routine.app and a drag-to-install `.dmg` with PyInstaller: see `docs/building-the-mac-app.md`.
`shared/icon.icns` is made from `shared/icon.svg` by `tools/make_icns.py` (no Mac needed).
`docs/mac-testing.md` is the checklist for trying it on a Mac.
## Pieces
```
shared/schedule.json the template routine (a first run starts from it; both apps)
shared/animations.json the animations + the star, frame by frame ← tools/gen_animations.py
shared/ANIMATIONS.md the catalogue: every one, its set, colour and sound (generated)
shared/sounds/*.wav one sound each ← tools/gen_sounds.py
shared/fonts/ Caveat (the note title's default font) + its licence
shared/icon.svg, icon.icns the app icon (the .icns ← tools/make_icns.py)
routine/ desktop app (PySide6); model.py is shared with the server (and has the streaks)
routine/qt/ the Qt binding: PySide6, else PyQt6
routine/system.py what differs on Linux and macOS (no Qt, tested)
routine/crash.py unhandled errors: logged (tracebacks only), a notice once, the app keeps going
routine/gui/frame.py the window chrome every window shares; SideWindow, the side windows' base
routine/gui/daterange.py the date range at the top of the side windows
routine/gui/history.py, stats.py, journal.py View → History / Statistics / Journal
routine/gui/history_cols.py the History grid's columns and marks (no Qt, tested)
routine/tally.py the Statistics and Journal figures (pure, tested)
routine/storage.py first run (the template), existing users, moving the data (no Qt, tested)
tools/anim_kit.py, sound_kit.py the drawing and synth helpers every animation / sound uses
tools/streak_anims/ the streak animations: levelK.py + levelK_sounds.py per level, calm.py
tools/fake_history.py a fake history in a scratch folder, to test with (never real data)
tests/ QT_QPA_PLATFORM=offscreen python3 -m unittest discover tests
(test_r1.py runs the R1's streak code on the JDK: android/src/test)
install-linux.sh, install-mac.sh the one-line installers (install, update, --uninstall)
scripts/build-mac-app.sh Routine.app + .dmg with PyInstaller, on a Mac
server/ routine-server, the sync relay → scripts/deploy-server.sh
android/ the R1 app (plain Java, no Gradle) → android/build.py
docs/ the screenshot, the Mac build and testing notes
```
`tools/preview_animations.py OUTDIR` draws every frame of every animation on contact sheets.
One streak level on its own, into a scratch folder (shared/ untouched):
```
python3 tools/gen_animations.py --level 0 --out DIR # DIR/animations.json + ANIMATIONS.md
python3 tools/gen_sounds.py --level 0 --out DIR # DIR/sounds/
python3 tools/preview_animations.py DIR/sheets --json DIR/animations.json --streak 0 [--number 465] [--every]
```
To try the app on fake data: `python3 tools/fake_history.py DIR`, then `ROUTINE_HOME=DIR python3 -m routine`
(it prints which tasks are one tick short of a streak level today). The installers can be tried
the same way, without touching your own install: `ROUTINE_SOURCE=. HOME=/tmp/x ./install-linux.sh`
(and `ROUTINE_INSTALL_TEST=1` lets `install-mac.sh` run on Linux).
## The sync server
Optional: without it the desktop app works on its own. With it, the desktop and the R1 keep each
other's ticks, notes and the routine. `server/routine_server.py` is standard-library Python (plus
`routine/model.py`), plain HTTP with a bearer token, so run it on a machine of yours that both
devices reach privately (a home server on a VPN such as WireGuard or Tailscale), not on the open
internet.
```
ROUTINE_SERVER_HOST=10.0.0.5 scripts/deploy-server.sh me@myserver # copy it there, (re)start it in screen
scripts/deploy-server.sh me@myserver --token # the token for Settings → Sync
scripts/deploy-server.sh me@myserver --stop
```
`DEPLOY_DIR` (default `routine-server` in the remote home) and `ROUTINE_SERVER_PORT` (default 8070)
change where and on what port; the address and port are kept in `DEPLOY_DIR/app/server.env`, so
a boot script on the server only has to run `DEPLOY_DIR/app/run.sh`. Then in the desktop app,
Settings → Sync: the address (`http://10.0.0.5:8070`) and the token; **Install / update on the R1**
hands both to the R1.