From 3d3f3e30b567b4f820fcbd724c94473a99476181 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Xos=C3=A9?= Date: Sun, 25 Oct 2026 09:05:33 +0100 Subject: [PATCH] Add spec.md: goal, limits and rules for working on the project Co-Authored-By: Claude Opus 5.5 --- spec.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 spec.md diff --git a/spec.md b/spec.md new file mode 100644 index 0000000..6a761d8 --- /dev/null +++ b/spec.md @@ -0,0 +1,56 @@ +# Calendar Lite (Android) — spec + +The short contract for working on this app. `README.md` is the user guide (and keeps the old TLS-bridge +setup); this file says what the app is for, what limits it lives within, and what must not break. + +## Goal + +A native Nextcloud (CalDAV) calendar for the Samsung Galaxy Mini that works at home and away, offline, +with reminders. + +## Target and hard limits + +- Samsung Galaxy Mini GT-S5570, Android 2.3.5 (API 9/10, `minSdkVersion` 8), 240×320 ldpi. +- Native Java, no libraries beyond the bundled TLS stack. No calendar-provider integration (2.3 has no + public API for it). +- Galician by default (weeks start Monday, month/day names built in), English in Settings. + +## Current scope (1.6) + +- Month view (6-week grid, colour marks, swipe, long-press to create) and Agenda view; choice remembered. +- SQLite cache of the last 35 days and the next 60 ("Days ahead"); months outside it fetched on demand. +- Create, edit and delete events (title, all-day, start/end, location, notes, alarm). Repeating events are + shown (server expansion, client fallback) and can be deleted, but are edited only in Nextcloud. +- Pick visible calendars and the default one for new events. +- Background sync every 1–24 h; notifications N minutes before timed events. +- Bundled TLS 1.2 to the normal `https://` address; pinned certificates for self-signed servers or the old + TLS 1.0 bridge (still supported). + +## Out of scope + +- Editing repeating events, tasks/VTODO, contacts, feeding the stock Samsung calendar. + +## Must not break + +- Package `org.gingercal` and `gingercal.keystore` (password `android`): updates install over GingerCal. +- Signing with `apksigner` v1 only; never `jarsigner` (that was the first build's bug). +- `src/` stays platform-neutral (CalDAV core runs on a desktop JVM for tests); Android code lives in + `android/`. +- `android/org/gingercal/net/` is a copy of `tlskit`, copied by hand (its `install.sh` doesn't handle this + path): change it in `../tlskit` first. +- `bridge/` stays working for anyone still on a bridge address. + +## Code map + +`src/` discovery, PROPFIND/REPORT, iCalendar, sync, pinning · `android/` activities, `SyncService`, alarms, +`Db` (SQLite), `NetHttp` · `stubs/` compile-only API 10 signatures · `bridge/` nginx legacy-TLS endpoint · +`tools/` dex/API checkers, zipalign, d8 workaround. + +## Build, test, release + +- `./build.sh` (finds d8, apksigner and apktool in `~/android-toolchain/calendar-tools`, and a JDK). Its own + route: javac → d8 → baksmali/smali → aapt v1 → apksigner v1 → zipalign → `apksigner verify` for API 8–10. +- Tests on the desktop JVM: `CoreTest` (needs Radicale on :5232, user `xose`/`secret`), `RedirectTest`, + `I18nTest`, `NetTest`. `tools/check_i18n.py` and `tools/check_api.py` run in the build. +- Release: raise `versionCode`/`versionName`, build, add `changes` in `../tenda-lite/repo/apps.json`, commit + and push, `../tenda-lite/repo/publish.sh`.