diff --git a/rules/patterns/backup-management/contract.md b/rules/patterns/backup-management/contract.md new file mode 100644 index 0000000..e61d7c6 --- /dev/null +++ b/rules/patterns/backup-management/contract.md @@ -0,0 +1,70 @@ +# Contract: Backup Management + +Version: 1.0 + +## Purpose + +Общие правила для создания, хранения, именования, ротации и восстановления бэкапов вне зависимости от того, что именно сохраняется: SQLite, централизованная БД, конфиг, файлы пользователя или смешанный bundle. + +## Backup Capability Must Be Shipped + +Backup/restore must be part of the application or its shipped operator tooling. Do not assume the operator already has suitable software installed on their machine. + +Rules: +- AI must not rely on random machine-local applications (DB GUI clients, IDE plugins, desktop backup tools, ad-hoc admin utilities) being present on the user's machine. +- If the application persists non-ephemeral state and does not already have backup functionality, implement it. +- Preferred delivery is one of: built-in UI action, CLI subcommand, background scheduler, or a shipped maintenance script/runbook that is part of the project. +- Rollout instructions must reference only shipped or implemented backup/restore paths. + +## Backup Storage + +Backups are operational artifacts, not source artifacts. + +Rules: +- Never write backups into the git repository tree. +- Backup files must never be staged or committed to git. +- Every application must have an explicit backup root outside the repository. +- Default local-app location: store backups next to the user config, for example `~/.config//backups/`. +- Default server/centralized location: store backups in an application-owned path outside the repository, for example `/appdata//backups/` or `/var/backups//`. +- Keep retention tiers in separate directories: `daily/`, `weekly/`, `monthly/`, `yearly/`. + +## Backup Naming and Format + +Rules: +- Each snapshot must be a single archive or dump artifact when feasible. +- Backup filenames must include a timestamp and a version marker relevant to restore safety, for example schema version, migration number, app version, or backup format version. +- If multiple artifacts are backed up independently, include the artifact identity in the filename. +- Backups should be archived/compressed by default (`.zip`, `.tar.gz`, `.sql.gz`, `.dump.zst`, or equivalent) unless restore tooling requires a raw dump. +- Include all sidecar files required for a correct restore. +- Include the application config in the backup when it is required for a meaningful restore. + +## Retention and Rotation + +Use bounded retention. Do not keep an unbounded pile of snapshots. + +Default policy: +- Daily: keep 7 +- Weekly: keep 4 +- Monthly: keep 12 +- Yearly: keep 10 + +Rules: +- Prevent duplicate backups within the same retention period. +- Rotation/pruning must be automatic when the application manages recurring backups. +- Pre-migration or pre-repair safety backups may be kept outside normal rotation until the change is verified. + +## Automated Backup Behavior + +For applications that manage recurring local or operator-triggered backups: + +Rules: +- On application startup, create a backup immediately if none exists yet for the current period. +- Support scheduled daily backups at a configured local time. +- If backup location, schedule, or retention is configurable, provide safe defaults and an explicit disable switch. + +## Restore Readiness + +Rules: +- The operator must know how to restore from the backup before applying risky changes. +- Restore steps must be documented next to the backup workflow. +- A backup that has never been validated for restore is only partially trusted. diff --git a/rules/patterns/go-database/contract.md b/rules/patterns/go-database/contract.md index 2de34b3..8aa2a7c 100644 --- a/rules/patterns/go-database/contract.md +++ b/rules/patterns/go-database/contract.md @@ -1,6 +1,6 @@ # Contract: Database Patterns (Go / MySQL / MariaDB) -Version: 1.1 +Version: 1.4 ## MySQL Transaction Cursor Safety (CRITICAL) @@ -115,6 +115,8 @@ This applies to: - Imports, bulk updates, and bulk deletes - Admin tools or one-off operator commands +Backup naming, storage, archive format, retention, and restore-readiness must follow the `backup-management` contract. + Rules: - No schema change or data mutation is allowed on a non-ephemeral database without a current backup. - "Small" or "safe" changes are not exceptions.