# 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