132 lines
5.7 KiB
Markdown
132 lines
5.7 KiB
Markdown
# Development Environment
|
|
|
|
## Purpose
|
|
Define the standard development environment for the WordPress calendar plugin so that development, testing, packaging, and deployment are consistent across contributors.
|
|
|
|
## Repository Layout
|
|
The repository is organized into the following top-level folders:
|
|
|
|
- `requirements/`: Functional and non-functional requirements.
|
|
- `docs/`: Documentation (test execution, installation, data structures, workflows).
|
|
- `code/`: Plugin source code.
|
|
- `compatibility-layer/`: Local WordPress emulation and stand-alone harness/shim code for tests.
|
|
- `tests/`: Automated and manual test assets.
|
|
- `package/`: Build outputs and distributable plugin package artifacts.
|
|
|
|
Note: the project convention may refer to `documentation/`; in this workspace the equivalent directory is `docs/`.
|
|
|
|
## Supported Development Platforms
|
|
Developers should use one of:
|
|
|
|
- Linux (preferred)
|
|
- macOS
|
|
|
|
Windows is acceptable when using WSL2 with a Linux userland.
|
|
|
|
## Core Tooling
|
|
Minimum expected tools:
|
|
|
|
- `bash` shell
|
|
- `ssh` client for remote test server access
|
|
- `zip` (or equivalent) for plugin packaging
|
|
- `rsync` or `scp` for deployment transfer
|
|
- Subversion (`svn`) and/or Git as required by the hosting/deployment workflow
|
|
|
|
If project scripts introduce additional dependencies (for example PHP CLI, Composer, Node.js, or WP-CLI), those requirements must be documented in `docs/` and kept aligned with this environment spec.
|
|
|
|
## Runtime Targets
|
|
Development and verification occur against two runtime targets:
|
|
|
|
1. Local compatibility harness (`compatibility-layer/`)
|
|
2. Remote WordPress test server (via SSH)
|
|
|
|
Production deployment is by packaged plugin artifact, not by direct source sync from `code/`.
|
|
|
|
Strict runtime/code separation requirements are defined in `requirements/architecture.md`.
|
|
|
|
## Local Development Workflow Expectations
|
|
- Implement plugin changes in `code/`.
|
|
- Keep requirements updates in `requirements/`.
|
|
- Add or update tests in `tests/`.
|
|
- Validate behavior first in the local compatibility harness (`compatibility-layer/`).
|
|
- Build distributable package into `package/`.
|
|
|
|
## Local Compatibility Harness Environment
|
|
The local harness in `compatibility-layer/` must emulate the WordPress functions/APIs needed by the plugin.
|
|
|
|
Environment expectations:
|
|
|
|
- Deterministic startup and teardown for repeatable tests.
|
|
- Isolated test data/state between runs.
|
|
- Ability to run plugin unit/integration-style tests without external network dependencies unless explicitly required.
|
|
- Clear commands documented in `docs/` for:
|
|
- harness startup
|
|
- test execution
|
|
- harness reset/cleanup
|
|
|
|
## Data Access Boundaries (Compatibility Harness and Tests)
|
|
When code under `code/` is exercised via the compatibility harness, data access must remain within approved WordPress mechanisms.
|
|
|
|
Requirements:
|
|
|
|
- Plugin code must access persistent data through WordPress-supported mechanisms (for example `$wpdb`, WordPress options/settings APIs, and documented plugin tables via WordPress DB access patterns).
|
|
- Plugin code must not bypass WordPress mechanisms by directly accessing external/non-WordPress data stores during compatibility-harness execution.
|
|
- Compatibility-harness and test runs must not depend on or read data outside the harness-managed test database/state.
|
|
- Any integration that requires external data access must be explicitly documented and excluded from default regression runs unless intentionally enabled.
|
|
|
|
## Remote Test Server Environment
|
|
Remote test validation is performed over SSH to a dedicated test environment.
|
|
|
|
Environment expectations:
|
|
|
|
- SSH access is key-based and restricted to authorized developers.
|
|
- Test server WordPress and PHP versions should mirror production as closely as practical.
|
|
- Deployment to test should use packaged plugin artifacts or an equivalent controlled sync process.
|
|
- Test data handling must avoid accidental production data access.
|
|
|
|
Required documentation in `docs/`:
|
|
|
|
- Host access method
|
|
- Deployment command(s)
|
|
- Rollback approach
|
|
- Post-deploy smoke test checklist
|
|
|
|
## Packaging and Deployment Environment
|
|
Production release uses a packaged plugin artifact produced from repository sources.
|
|
|
|
Detailed remote deployment and exact-match validation requirements are defined in `requirements/deployment.md`.
|
|
|
|
Packaging expectations:
|
|
|
|
- Package is generated in `package/` with versioned naming.
|
|
- Artifact contains only required plugin files.
|
|
- Development-only files (temporary files, compatibility-layer artifacts, etc.) are excluded.
|
|
- Package integrity is validated before deployment.
|
|
|
|
Deployment expectations:
|
|
|
|
- Upload/install package on production server via approved operational process.
|
|
- Record deployed version and deployment timestamp.
|
|
- Maintain a rollback artifact for the previous known-good release.
|
|
|
|
## Configuration and Secrets
|
|
- Do not commit secrets to source control.
|
|
- SSH credentials/keys, server addresses, and environment-specific configuration must be stored outside the repo (or in approved secret management).
|
|
- Local and remote environment variables should be documented by name and purpose in `docs/` without exposing secret values.
|
|
- Compatibility-harness email workflows use SMTP variables sourced from `credentials/.env` (or process env):
|
|
- `SMTP_HOST`, `SMTP_PORT`, `SMTP_USE_TLS`, `SMTP_USERNAME`, `SMTP_PASSWORD`, `SMTP_FROM`, `SMTP_ADMIN_TO`
|
|
|
|
## Quality Gates
|
|
Before packaging for test or production:
|
|
|
|
- Requirements impacted by change are updated.
|
|
- Relevant tests in `tests/` pass in local compatibility harness.
|
|
- Remote test server smoke checks pass.
|
|
- Package contents are verified.
|
|
|
|
## Change Control
|
|
Any material change to tools, runtime versions, harness behavior, or deployment process must update:
|
|
|
|
- this file (`requirements/environment.md`)
|
|
- corresponding operational docs in `docs/`
|