calendar-plugin/requirements/packaging.md

Plugin Packaging Requirements

Purpose

Define the required process for creating a production-ready WordPress plugin package artifact from this repository.

Scope

This document covers:

• Preparing package contents from repository sources
• Building a distributable archive
• Validating the archive before deployment

It does not cover:

• Production installation steps
• Runtime plugin behavior

Deployment execution and remote exact-match validation are defined in requirements/deployment.md. Runtime/code separation constraints are defined in requirements/architecture.md.

Source and Output Locations

• Source code root: code/
• Packaging workspace/output: package/
• Tests used for pre-package validation: tests/

Packaging Preconditions

Before creating a package:

• Relevant tests pass in the local compatibility harness.
• Plugin version for release is set in plugin metadata/files.
• Working tree contains intended release changes only.
• Required build tools (zip or equivalent) are available.

Package Content Rules

The package must include only files required to run the plugin in WordPress.

Required inclusions:

• Main plugin file and all runtime PHP source under code/
• Runtime assets (CSS/JS/images) required by plugin features
• Any required vendor/runtime dependencies needed in production
• License/readme files required by project policy

Required exclusions:

• tests/, compatibility-layer/, and local development-only assets
• Temporary files, editor files, OS metadata files
• Build scripts and internal notes not needed at runtime
• Secrets, credentials, or environment-specific private data

Package Structure Requirements

• The archive must expand into a single plugin directory.
• The plugin directory name must be stable and suitable for WordPress plugin installation.
• Directory structure inside the package must preserve runtime-relative paths expected by plugin code.

Build Procedure Requirements

Packaging process must be deterministic and repeatable.

Required steps:

1. Create/clean a staging folder under package/.
2. Copy approved runtime files from code/ into staging.
3. Apply exclusion rules to remove non-runtime artifacts.
4. Increment plugin patch version (X.Y.Z -> X.Y.(Z+1)) for each package build unless an explicit version override is provided.
5. Keep runtime-visible version fields synchronized for the package (plugin header version and health/API version metadata).
6. Create a versioned zip archive in package/.
7. Record artifact name and version in release notes/changelog.

Artifact naming requirement:

• Use a versioned filename pattern, for example: <plugin-slug>-<version>.zip

Validation Requirements

Before the artifact is accepted:

• Archive can be opened successfully.
• Archive root contains exactly one plugin folder.
• Main plugin entry file exists at expected location.
• No excluded directories/files are present.
• No files from compatibility-layer/ are present.
• Plugin activates successfully in local compatibility-harness/test environment.

Integrity and Traceability

• Each package build must be traceable to a source revision/tag.
• Build date/time and source revision should be recorded with the artifact.
• Rebuilding from the same revision should produce functionally equivalent contents.

Failure Handling

If packaging fails validation:

• Artifact must not be promoted to test or production.
• Failures must be documented with cause and remediation.
• Packaging is re-run only after corrective changes are applied.

Documentation Requirements

Project docs must include:

• Exact packaging command(s) used
• Exclusion/inclusion rules
• Artifact naming convention
• Validation checklist
• Location of produced archives