327 lines
21 KiB
Markdown
327 lines
21 KiB
Markdown
# Routine
|
||
|
||

|
||
|
||
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.
|