calendar-plugin/requirements/life_cycle.md

Plugin Life Cycle (Production)

Purpose

Define the production-server lifecycle for the calendar plugin, including installation, configuration, ongoing data maintenance, and uninstallation behavior.

Scope

This requirement applies to:

• First-time installation on production
• Plugin upgrades on production
• Operational maintenance of plugin-owned data
• Uninstallation from production

Preconditions

Before installation:

• The production WordPress instance is healthy and backed up.
• The plugin package artifact has been built and verified.
• Deployment user has appropriate WordPress admin permissions.
• Database user configured for WordPress has permission to create/alter/drop plugin tables.

Installation (Production)

Installation must be performed using the packaged plugin artifact through approved production procedures.

Required behavior on activation:

• Register plugin activation logic using WordPress plugin lifecycle hooks.
• Create/update required plugin database schema using WordPress APIs only.
• Initialize plugin default options/settings in WordPress options storage.
• Record plugin schema/version metadata for future migrations.

Database Table Creation (WP APIs Only)

Plugin-owned tables must be created and migrated via WordPress APIs only; direct shell/database tooling is not part of normal runtime lifecycle.

Requirements:

• Use $wpdb for table naming with WordPress table prefix support.
• Use dbDelta() (from WordPress upgrade API) for table creation and compatible schema updates.
• Use WordPress charset/collation helpers (e.g., $wpdb->get_charset_collate()).
• Version schema changes using a stored option (for example, plugin schema version option).
• Table creation/migration must be idempotent and safe to run multiple times.

Non-requirements:

• No raw CLI SQL execution as part of plugin activation/deactivation lifecycle.

Server Configuration and Settings

On production install, plugin settings must be configurable in WordPress admin and persisted using WordPress settings/options APIs.

Requirements:

• Register settings via WordPress Settings API.
• Validate and sanitize all user-provided settings before persistence.
• Apply secure defaults during first activation.
• Restrict configuration UI/actions to authorized WordPress capabilities.
• Document required settings and operational defaults in project docs.

Data Maintenance on Server

The plugin must maintain its production data safely across normal operation and upgrades.

Requirements:

• Maintain backward-compatible migrations for schema evolution where practical.
• Preserve data on plugin upgrades by default.
• Avoid destructive data operations during activation/deactivation unless explicitly required by migration logic.
• Provide routine cleanup/retention behavior only through explicit plugin logic (e.g., scheduled cleanup), not implicit uninstall behavior.
• Log or surface migration/maintenance failures via WordPress-compatible error/reporting paths.

Upgrade Lifecycle

On plugin update:

• Activation/upgrade routine checks stored plugin/schema version.
• Required migrations run in deterministic order.
• Migration completion updates stored schema/version markers.
• Existing user settings are preserved unless a documented migration transforms them.

Uninstallation (Production)

Uninstall must support two outcomes:

1. Remove plugin code but keep plugin database data.
2. Remove plugin code and remove plugin database data.

Uninstall behavior must be explicit and predictable.

Data Retention Option

Requirements:

• Provide an administrator-controlled setting (or equivalent explicit control) named clearly for data retention on uninstall.
• Default behavior should be conservative: keep data unless administrator explicitly chooses removal.
• The retention setting must be read during uninstall execution.

Uninstall Execution

Requirements:

• Implement uninstall logic using WordPress uninstall mechanisms (uninstall.php and/or uninstall hook).
• Always remove plugin options/settings that are not required after uninstall when full removal is selected.
• If “keep data” is selected:
  • Leave plugin-owned database tables and business data intact.
  • Remove only runtime/transient/cache entries where appropriate.
• If “remove data” is selected:
  • Drop plugin-owned tables via WordPress database APIs ($wpdb), respecting table prefixes.
  • Delete plugin-owned options, metadata, and scheduled tasks.
  • Ensure cleanup is scoped only to this plugin’s data.

Safety and Recovery

Requirements:

• Uninstall must never affect WordPress core tables or other plugins’ data.
• Destructive cleanup must require explicit administrator intent through the retention setting.
• Operational runbooks should include pre-uninstall backup guidance.
• If uninstall cleanup partially fails, failures must be detectable (admin notice/log entry) for manual remediation.

Verification Requirements

Production lifecycle acceptance should verify:

• Fresh install creates required tables/options.
• Re-activation is idempotent.
• Upgrade runs required migrations without data loss.
• Uninstall with “keep data” preserves plugin tables/data.
• Uninstall with “remove data” removes plugin-owned tables/options/scheduled tasks.

Documentation Requirements

The following must be documented in project docs:

• Production installation steps
• Required server permissions
• Configuration options and defaults
• Upgrade/migration behavior
• Uninstall procedure with keep/remove data choice
• Recovery procedure for failed migration or uninstall cleanup