# 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. Create a versioned zip archive in `package/`.
5. 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