67 lines
3.0 KiB
Markdown
67 lines
3.0 KiB
Markdown
# RecoReco -- calendar-scheduled recurring cards
|
|
|
|
Kanboard's built-in recurrence is event-triggered (a card recurs when you move or close it).
|
|
RecoReco adds **calendar-triggered** recurrence: a card fires on a date, on its own, via cron --
|
|
made for bills, rent, and subscriptions.
|
|
|
|
A card marked recurring **stays** as a template; on schedule, RecoReco spawns a plain
|
|
(non-recurring) copy into a column you choose. The template advances to the next date; the copy
|
|
keeps the fired date.
|
|
|
|
RecoReco is opt-in per card and inert until you mark a card, so it needs no per-board setting. It
|
|
leaves native recurrence untouched (the two are mutually exclusive per card).
|
|
|
|
## The idea
|
|
|
|
- **The due date is the anchor.** All timing (day, month, weekday, time) is read from the card's
|
|
due date -- there are no separate date inputs. A card without a due date cannot be made recurring.
|
|
- **Frequencies:** yearly, monthly by day, monthly by weekday, weekly, daily.
|
|
- **Last day of the month:** an explicit checkbox (honored only when the due date is the last day,
|
|
or the last such weekday, of its month).
|
|
- **Lead time:** "create the copy N days before the due date", so the card shows up early enough
|
|
to act on; the copy is still due on the real day.
|
|
|
|
## Scheduling (cron)
|
|
|
|
The engine runs from the CLI command `recoreco:run`. Add it to cron **four times a day** -- at
|
|
05:58, 11:58, 17:58 and 23:58:
|
|
|
|
```
|
|
58 5,11,17,23 * * * cd /path/to/kanboard && php cli recoreco:run >> /var/log/recoreco.log 2>&1
|
|
```
|
|
|
|
(Point the path at your install and run it as the user that owns Kanboard's data.) Each run looks
|
|
ahead 12 hours; the runs overlap by 6 hours, so a single missed run is covered by the next one.
|
|
|
|
Each run walks a template forward from its current due date and spawns **every** occurrence whose
|
|
fire time has arrived -- so occurrences already in the past are backfilled, not skipped. To avoid
|
|
flooding the board when a template was set far in the past, a single run spawns at most the **12
|
|
most recent** due occurrences; any older overflow is skipped (contiguous, no gap) and the template
|
|
advances straight to the next future occurrence. `days before` shifts a copy earlier within the
|
|
lead. Runs are idempotent: an occurrence is never spawned twice, so running an extra time is safe.
|
|
|
|
You can trigger the exact same pass by hand -- either on the CLI (`php cli recoreco:run`) or with
|
|
the **Run now** button under **Settings -> RecoReco** (admin only). The button and cron do the
|
|
identical thing.
|
|
|
|
## Status
|
|
|
|
All five frequencies work (yearly, monthly by day, monthly by weekday, weekly, daily) with the
|
|
last-day rule, board recurrence icons, backfill with the 12-occurrence cap, the Run-now button, and
|
|
the FinanceBuddy installment hand-off.
|
|
|
|
## Requirements
|
|
|
|
- Kanboard >= 1.2.0
|
|
- cron (to run `recoreco:run`)
|
|
|
|
## Installation
|
|
|
|
Copy this folder into your Kanboard installation as `plugins/RecoReco/`. The directory name must be
|
|
exactly `RecoReco` (Kanboard derives the plugin namespace from the folder name). No build step and
|
|
no database migration. Then add the cron entry above.
|
|
|
|
## License
|
|
|
|
AGPL-3.0. See LICENSE.
|