diff --git a/Plugin.php b/Plugin.php index 4f9507a..ee8d733 100644 --- a/Plugin.php +++ b/Plugin.php @@ -81,7 +81,7 @@ class Plugin extends Base public function getPluginVersion() { - return '0.6.0'; + return '1.0.0'; } public function getPluginHomepage() diff --git a/README.md b/README.md index a9d069b..9f96875 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,132 @@ -# Skeleton -- a Kanboard plugin template +# QualKard -- flashcard spaced repetition on your Kanboard -A minimal, working Kanboard plugin that you copy and rename as the starting point for a -real plugin. By itself it does only one trivial thing: it renders the word "Skeleton" at -the top of every page. It changes no data and runs no database migration. +Turn a Kanboard board into a spaced-repetition flashcard deck. Each card is a flashcard -- +title is the prompt, description is the answer. You study a card, grade how it went by +dragging it into a grade column, and QualKard schedules when it should come back. Cards you +find easy drift far into the future; hairy ones return tomorrow. -## What it demonstrates +The scheduling math is ported from Ruben's C program **qualcard** (the "K" here just marks the +Kanboard port). The card movement -- bringing a card back when it falls due -- is done by the +companion **RecoReco** plugin, so QualKard needs RecoReco installed and RecoReco's cron running. -- A complete `Plugin.php` registration class with all the metadata Kanboard shows in - Settings -> Plugins (name, description, author, version, homepage, compatible version). -- A template hook (`template:layout:top`) that injects a template into the page. -- Asset hooks (`template:layout:css` and `template:layout:js`) that load a stylesheet and - a script. They are empty for now but prove the injection path works -- handy when a real - plugin needs custom CSS or JS. -- The standard plugin directory layout, with stub folders (`Controller/`, `Model/`, - `Schema/`, `Locale/`, `Test/`) ready to grow into. +QualKard is **opt-in per board**: installing it changes nothing until a project manager sets a +specific board up under Settings -> Integrations. Setting a board up **restructures its +columns**, so it is a deliberate, confirmed action -- see below. + +## The study board + +Setting a board up gives it exactly seven columns, each with a fixed role: + +``` +Drafts | Study | Hairy | Hard | Medium | Easy | Done +``` + +- **Drafts** -- where new and reset cards wait. A draft is inert: it never comes due on its own. +- **Study** -- the review queue. RecoReco moves a card here when it falls due; this column is + itself the "overdue" backlog, so it can hold more than one day's worth. +- **Hairy / Hard / Medium / Easy** -- the four grade columns. You review a card in Study, then + drag it into one of these to record how it went. +- **Done** -- a resting place you drag a card to when you want it out of rotation. A card in Done + does not come back (it is the one column that does not re-trigger). + +## Studying + +1. Read the prompt (the card title) in **Study**, recall the answer, then open the card to check + the description. +2. Drag the card into the grade column that matches how it went: + + | Column | Meaning | Score | + |--------|---------|------:| + | Hairy | no idea / wrong | 0.0 | + | Hard | right, but a struggle | 1.3 | + | Medium | right, some effort | 3.0 | + | Easy | instant | 5.0 | + +3. QualKard folds that score into the card's running average and sets the card's **due date** the + right number of days out (1 day for a hairy average, up to 11 for a mastered one). RecoReco + picks the card up from the grade column and, when it next falls due, moves it back to **Study**. + +You never edit a due date or move a card back yourself -- grading is the only action. + +### How the schedule is computed + +Each card keeps a running average of its scores. A brand-new card is seeded a little below its +first score; after that the average is the mean of the old average and the new score. The average +maps to an interval: + +| Average | Interval | +|------------|---------:| +| <= 0.60 | 1 day | +| <= 1.35 | 2 days | +| <= 2.20 | 3 days | +| <= 3.05 | 5 days | +| <= 3.90 | 7 days | +| <= 4.92 | 9 days | +| otherwise | 11 days | + +So a card you keep grading Easy climbs toward an 11-day gap, while one you keep missing stays at a +day or two until it sticks. + +## The mastery badge + +Each card shows a small badge under its title, on the board and at the top of the opened card: + +- **new** (yellow) -- an unread card that has never been graded. +- a **percent** of mastery (the average as a fraction of 5), coloured **red** below 50%, + **green** through 89%, and **blue** at 90% and up. ## Requirements - Kanboard >= 1.2.0 +- The **RecoReco** plugin, installed and enabled, with its cron task running (RecoReco is what + moves due cards back to Study). QualKard's setup button stays disabled until RecoReco is present. + +QualKard refuses to set up a board that has **FinanceBuddy** enabled: the restructure would wreck a +finance board's columns. Disable FinanceBuddy on that board first, or use a different board. ## Installation -No build step and no dependencies. +Copy this folder into your Kanboard installation as `plugins/QualKard/`. The directory name must be +exactly `QualKard` (Kanboard derives the plugin namespace from the folder name). No build step and +no database migration. -1. Copy this folder into your Kanboard installation as `plugins/Skeleton/`. -2. Reload any page. The word "Skeleton" appears at the top. -3. Confirm it under Settings -> Plugins. +Then, on the board you want to study: -To uninstall, delete `plugins/Skeleton/`. Nothing else is left behind. +1. Go to Settings -> Integrations. +2. Under QualKard, click **Set up QualKard study board**, and confirm. This renames the board's + columns to the seven roles above (creating or removing columns to reach exactly seven) and moves + every existing card into Drafts. +3. Make sure RecoReco's cron is running so due cards come back. -## Directory layout +From the same page you can later **Reset all cards** (send every card back to Drafts, unread) or +**Disable QualKard machinery** (stop the automation without touching your columns or cards). -``` -Skeleton/ - Plugin.php Registration and hook wiring (the only required file). - README.md - LICENSE AGPL-3.0. - Template/ - layout/header.php The visible "Skeleton" word. - Asset/ - css/skeleton.css Loaded via template:layout:css. - js/skeleton.js Loaded via template:layout:js. - Controller/ Stub for future request handlers. - Model/ Stub for future business logic / DB access. - Schema/ Stub for future database migrations. - Locale/ Stub for future translations (e.g. pt_BR/, fr_FR/). - Test/ Stub for future unit tests. -``` +## How it stores data -## How to fork this into a new plugin - -1. Copy the folder and rename it, e.g. `plugins/MyPlugin/`. The folder name must match the - namespace and start with a capital letter. -2. In `Plugin.php`, change the namespace from `Kanboard\Plugin\Skeleton` to - `Kanboard\Plugin\MyPlugin`. -3. Update the metadata methods (`getPluginName`, `getPluginDescription`, `getPluginAuthor`, - `getPluginVersion`, `getPluginHomepage`, `getCompatibleVersion`). -4. Update the hook target paths: the lowercase prefix in `'skeleton:layout/header'` and the - `plugins/Skeleton/Asset/...` asset paths must match the new plugin name. -5. Replace `Template/layout/header.php` with your real template, or attach to a different - hook. See the Kanboard plugin hooks documentation for the full list of hook points. +No database migration. The per-board enable flag and the seven column roles are stored in project +metadata; each card's running average lives in task metadata, and QualKard writes the card's due +date and RecoReco's per-card recurrence config. Uninstalling the plugin leaves that metadata +harmlessly in place -- your columns and cards are untouched. ## License AGPL-3.0. See LICENSE. + +## More Kanboard plugins by Ruben (drbeco) + +All free and AGPL-3.0, at [code.beco.cc](https://code.beco.cc/beco): + +- **[RecoReco](https://code.beco.cc/beco/RecoReco)** -- calendar-scheduled recurring cards (yearly, + monthly, weekly, daily), driven by the card due date. QualKard rides RecoReco's move engine to + bring due flashcards back to the Study column. +- **[FinanceBuddy](https://code.beco.cc/beco/FinanceBuddy)** -- attach a money value to each card, + show it on the card, and total it per column, so a board can double as a simple finance board. +- **[OrganonTweaks](https://code.beco.cc/beco/OrganonTweaks)** -- an umbrella of small + quality-of-life board tweaks: remove an empty column, always show the comment icon, emphasize due + dates, extra search keywords and shared board filters, and more. +- **[BulkMoveTasks](https://code.beco.cc/beco/BulkMoveTasks)** -- move every task from one board + column to another in a single action. +- **[ShrinkVertically](https://code.beco.cc/beco/ShrinkVertically)** -- shrink vertically-collapsed + board columns so the horizontal scrollbar stays within reach. +- **[TweakDrag](https://code.beco.cc/beco/TweakDrag)** -- board drag and touch niceties: + drag-to-scroll, a wider column gap, and smoother card dragging. diff --git a/VERSION b/VERSION index 6f903ea..71749bb 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -QualKard v0.6 +QualKard v1.0