131 lines
5.5 KiB
Markdown
131 lines
5.5 KiB
Markdown
# 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
|