Files
matrix-bot/docs/UPGRADE.md
T

37 lines
3.5 KiB
Markdown

# Upgrade from static modules
## Behavior changes
- `rooms` replaces static bot-module registration. The host discovers plugin manifests automatically.
- A room's plugin state and reply language persist. After the first activation, stored choices override configuration defaults.
- Check-in day boundaries are local midnight in the configured timezone. Reports no longer reset daily or monthly data.
- Manual report queries are read-only. Legacy reset, test and manual-level commands no longer execute their previous behavior.
- Other-user, all-user and raw check-in queries require administrator access.
- Cleanup requires `cleanupEnabled`; automatic cleanup additionally requires `autoCleanup`. The legacy `autoKick` field is not carried forward as authorization for the new cleanup workflow.
- Membership management defaults to independent business roles. All automatic membership switches default to false. To retain native power mapping, explicitly choose `mode: matrix` and the required synchronization switches.
- Native administrators are exempt from membership removals. Failed permission lookups do not authorize removals.
- Startup does not announce each plugin. Re-enabling a plugin may deliver due report notifications, and explicitly enabled membership reconciliation can run on enable.
- Old command events preceding the current Matrix session process are ignored to avoid replaying administrative actions. Optional reconciliation works from current membership state.
## Configuration
Use the example `rooms` format for new deployments. The legacy `bots` format is normalized into one plugin instance per account/room, but it should be replaced during upgrade. Do not mix `rooms` and `bots` in one file. Reports are local to each plugin instance; the old `mainRoom` aggregation setting is no longer used.
For a legacy `checkin` bot bound to exactly one account and one room, the migration target is inferred. When shared records previously covered multiple rooms, select exactly one destination explicitly:
```yaml
legacyCheckinTarget:
account: main
roomId: "!control:example.org"
```
The destination must exist in `rooms` and have a configured `checkin` plugin. New room configurations using an old database also need this target. Migration refuses an ambiguous destination, an already populated destination without a migration marker, malformed source records or reassignment after a completed migration.
## Data conversion
The old table used `checkin` as a shared storage scope. Version 2 scopes records by account, room and plugin. Migration copies records and writes its completion marker in one transaction; it leaves the original rows intact.
The legacy schema contains the current monthly count and last check-in timestamp, not a complete daily or lifetime history. Migration preserves the known monthly count as a baseline and the last check-in date as a non-counting daily record. This prevents double counting or a second check-in on that date. Earlier daily dates and earlier monthly totals cannot be reconstructed. The displayed cumulative total is therefore the known baseline plus new records, not an invented lifetime total. Legacy levels are recalculated from that known total. Source data remains available for an explicit future reconciliation if additional history is available.
Take a consistent backup before the first upgraded startup. A code rollback alone does not copy new v2 activity back into legacy records; restore a compatible backup or explicitly reconcile subsequent activity. Migration runs during service initialization, before Matrix sessions start.