calendar-plugin/requirements/deployment.md

Deployment Requirements

Purpose

Define how the plugin is deployed to the remote WordPress host and how deployment correctness is verified, including an exact-match validation between the approved artifact and deployed runtime files.

Scope

This document covers:

• Remote host deployment target and access assumptions
• Artifact-only deployment model
• Pre-deploy checks
• Post-deploy validation
• Exact-match validation requirements
• Rollback requirements

This document does not define packaging rules (see requirements/packaging.md) or runtime feature behavior.

Normative References

• Packaging requirements: requirements/packaging.md
• Environment/runtime requirements: requirements/environment.md
• Architecture/runtime separation requirements: requirements/architecture.md
• Smoke/regression expectations: tests/smoke_tests.md

Deployment Model

• Deployments must use a built plugin artifact (zip) produced from approved repository content.
• Direct ad-hoc editing of production plugin files is not permitted.
• Deployment target path must point to the active WordPress plugin directory.
• Deployable runtime must come from code/ only; compatibility/emulation assets are not deployable.

For the current remote test target:

• WordPress root: /var/www/wordpress
• Plugin directory root: /var/www/wordpress/wp-content/plugins
• Plugin deploy directory: /var/www/wordpress/wp-content/plugins/calendar-plugin

Pre-Deployment Requirements

Before deployment:

1. Package artifact has passed packaging validation.
2. Local and remote smoke checks required for the release scope are green.
3. Remote path existence/permissions are verified.
4. Backup or rollback artifact for currently deployed version is available.
5. Deployment record includes target host, artifact name, version, timestamp, and operator.

Deployment Procedure Requirements

Required high-level procedure:

1. Build a fresh deploy artifact as part of deploy execution (package step) using the current repository state.
2. Transfer approved artifact to remote host staging area.
3. Extract artifact to a clean temporary directory on remote host.
4. Validate extracted plugin directory structure.
5. Synchronize extracted plugin directory to deploy directory.
6. Run post-deploy verification checks.

Additional policy requirement:

• Deploy flow should not bypass packaging by deploying an arbitrary stale artifact path; deployment must use the freshly built artifact for that deploy run.
• Deployment tooling may support an explicit version override for controlled releases (for example 1.0.0); when used, that explicit version must be the packaged and deployed artifact version for that run.

Exact-Match Validation (Required)

After deployment, deployed plugin files must exactly match the approved artifact contents (excluding allowed mutable runtime files if any are explicitly listed).

Validation must include:

1. File set equality:

• No missing files in deployment compared to artifact.
• No extra files in deployment compared to artifact.

2. File content equality:

• Each deployed file content hash must match artifact file hash.

3. Optional metadata check (recommended):

• File mode/permissions match expected deployment policy.

Accepted implementation options:

• Manifest-based validation: generate a sorted list of <relative-path> <sha256> from extracted artifact and deployed directory and compare byte-for-byte.
• Rsync dry-run checksum validation (for example rsync -avznc --delete) plus explicit failure on any reported delta.

Any mismatch must fail deployment validation and trigger rollback decision.

Post-Deployment Verification Requirements

After exact-match validation:

1. Plugin is present and loadable by WordPress.
2. Plugin activation state is verified (as required by release process).
3. CalDAV endpoint discovery and ICS endpoint health checks pass.
4. Critical UI/API smoke checks pass.

Rollback Requirements

If deployment validation or post-deploy checks fail:

1. Revert to previous known-good plugin artifact.
2. Re-run minimum smoke checks to confirm recovery.
3. Record incident details and remediation before next deploy attempt.

Audit and Traceability Requirements

Each deployment must record:

• artifact name/version
• source revision/tag
• target host/path
• deploy timestamp
• validation result (including exact-match evidence)
• rollback status if applicable

Acceptance Criteria

Deployment process is acceptable only if:

1. Artifact-only deployment is enforced.
2. Exact-match file and hash validation is performed and passes.
3. Required post-deploy smoke checks pass.
4. Deployment record contains all traceability fields.