Jean-Luc Makiola
13cb27b2ab
The vendored dmfs provider was kept on the grounds that it hands us the sync bookkeeping for free. The phase-1 sync audit measured that bookkeeping and found most of it broken, absent, or unusable: _DIRTY not set on delete, no home for a per-collection sync token, read-only collections inexpressible, ACCOUNT_TYPE write-once so enabling sync is a full migration, and cleanUpLists able to delete a user's lists after a backup restore. Sixteen findings are provider-imposed rather than platform- or protocol-imposed. Costing the alternative showed the swap is far smaller than assumed. TasksDataSource is already a 14-method, domain-shaped interface; exactly one file above the data layer references TasksContract. The work is a second implementation behind an interface built for it, not a rewrite. Against ~5 weeks to build, owning the store removes 2.5-4 weeks from the sync plan, and 8,200 of the vendored 14,555 lines are things we would never write - 23 migrations from a 2013 schema, 798 lines of full-text search the app has zero call sites for, and 1,581 lines of a type-safe layer over ContentValues that Room deletes. External mode (OpenTasks, tasks.org) is unaffected and keeps every file that describes somebody else's schema. STORAGE-DECISION.md is the reasoning; OWN-STORE.md is the architecture and the six-phase plan. :provider stays in-tree until phase 5 so recurrence parity can be tested against it before it goes. Also corrected here: the provider's JVM test count (51 -> 56, measured from the test-results XML) and a fourth site of the debunked "switching sync on is never a migration" claim, in StorageMode.kt. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
39 lines
2.9 KiB
Markdown
39 lines
2.9 KiB
Markdown
# Agendula — documentation
|
||
|
||
Agendula is a Material 3 Expressive **task** app for Android. It **carries its
|
||
own task store** — the dmfs task provider vendored under our own authority — so
|
||
it is complete and local-first with nothing else installed; an external provider
|
||
(OpenTasks / tasks.org, synced by DAVx5 / SmoothSync / DecSync) is a user choice
|
||
rather than a requirement, and our own CalDAV sync is the 1.x arc. Sibling to
|
||
[Calendula](https://codeberg.org/jlmakiola/calendula). See the
|
||
top-level [`../README.md`](../README.md) for the project pitch.
|
||
|
||
## Index
|
||
|
||
| Doc | What it covers |
|
||
|---|---|
|
||
| [`ARCHITECTURE.md`](ARCHITECTURE.md) | How Agendula is built **today** — layers, the data seam, provider resolution, the reminder engine, DI, build/tooling, manifest. Start here to work on the code. |
|
||
| [`ROADMAP.md`](ROADMAP.md) | **Status** and what's next — milestones (M0–M6 + Posture B), what's done, open decisions, how to build/verify. |
|
||
| [`STORAGE-AND-SYNC.md`](STORAGE-AND-SYNC.md) | **Where task data lives** — the decision to ship our own provider, the storage modes, permissions, distribution, and the dead ends. Supersedes `PLAN.md` on storage. |
|
||
| [`SYNC.md`](SYNC.md) | **How data reaches a server** — the CalDAV sync adapter: the VTODO ↔ `TaskContract` mapper, Nextcloud sign-in, the engine, libraries and their licenses. Step 5 of `STORAGE-AND-SYNC.md`. |
|
||
| [`STORAGE-DECISION.md`](STORAGE-DECISION.md) | **Keep the vendored provider, or build our own?** The measured cost of both. **Decided: build our own.** |
|
||
| [`OWN-STORE.md`](OWN-STORE.md) | **Agendula's own Room store** — the schema, recurrence design, migration off the vendored provider, and the six-phase plan that deletes `:provider`. Supersedes the "keep the provider" position in `STORAGE-AND-SYNC.md`. |
|
||
| [`PLAN.md`](PLAN.md) | The original implementation plan and **design rationale** — the A-now-B-later thesis, what transfers from Calendula, the locked decisions. The "why". |
|
||
| [`RELEASING.md`](RELEASING.md) | How to cut a release — the git-tag-as-source-of-truth flow, CI jobs, F-Droid repo, required secrets. |
|
||
| [`../provider/PROVENANCE.md`](../provider/PROVENANCE.md) | What the vendored `:provider` module is, where it came from, and **every** deviation from upstream dmfs. |
|
||
|
||
Also: [`../CHANGELOG.md`](../CHANGELOG.md) (Keep a Changelog format; tag sections
|
||
feed the release notes).
|
||
|
||
## How the docs relate
|
||
|
||
- **PLAN** is the original design decisions (the "why"), left as the historical
|
||
record. On storage it is **superseded by STORAGE-AND-SYNC**.
|
||
- **STORAGE-AND-SYNC** and **SYNC** are the standing decision documents: the
|
||
first settles where data lives, the second how it syncs. Both record rejected
|
||
alternatives on purpose, so decisions don't get relitigated.
|
||
- **ARCHITECTURE** is the current shape of the code (kept in sync with the
|
||
source as it grows).
|
||
- **ROADMAP** is the moving status layer (update as milestones land).
|
||
- **RELEASING** is the operational runbook.
|