adrians
/
calendar-plugin
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
calendar-plugin/requirements/environment.md

5.7 KiB
Raw Blame History

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/