103 lines
3.7 KiB
Markdown
103 lines
3.7 KiB
Markdown
# 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
|