Skip to content

Bamboo v1.0 API Freeze Preparation

This planning note captures the contract surfaces that must be frozen ahead of the v1.0 milestone and the supporting documentation deliverables that keep the community aligned. Each section highlights the review checkpoints required before cutting the release candidate so breaking changes are surfaced early and compatibility guarantees are explicit.

Public API surfaces slated for freeze

CLI command palette

Bamboo's dot-notation CLI is the operational front door for most users. The freeze ensures command names, required arguments, and structured output remain stable across the 1.x line.

  • [x] Review the complete command roster (bin/bamboo list) and document stability levels for each entry (stable, experimental, or internal).
  • [x] Capture input/output contracts for critical commands (http.serve, routes.cache, queue.work, dev.watch, etc.) in docs/cli/ reference pages before the freeze.
  • [x] Establish guardrails for future additions: new commands require semver minor releases, and renames must ship with deprecated aliases for at least one minor release.
  • [x] Publish a CLI deprecation policy in the upgrade guide describing how long aliases are maintained and how operators are notified (release notes + runtime warnings).

HTTP router contract

Routes define the public HTTP surface for applications built on Bamboo. Freezing method matching, parameter binding, and error behaviour gives downstream teams confidence that v1.x upgrades will not break HTTP integrations.

  • [x] Enumerate supported HTTP methods, route declaration helpers, and parameter token formats in docs/router.md with code examples.
  • [x] Validate that 404/405/500 response payloads and status codes are covered by contract tests and describe them in the API docs.
  • [x] Document middleware ordering guarantees (global → group → route) and ensure the behaviour is regression-tested in tests/Router/ suites.
  • [x] Define the router deprecation story: route helper removals must emit E_USER_DEPRECATED notices and remain available through at least v1.(x+1).

Module extension API

Modules implement Bamboo\Module\ModuleInterface to extend the framework. Freezing this contract stabilises how third-party packages integrate with the core container and middleware system.

  • [x] Audit the module lifecycle (register, boot, middleware) and confirm no additional hooks are required for the v1.0 baseline. Documented in docs/modules.md with timing guarantees.
  • [x] Document module discovery and configuration expectations in docs/modules.md, including examples for publishing middleware aliases and services.
  • [x] Define semantic-versioning rules for modules: breaking interface changes require a major release, and optional method additions must provide sane defaults.
  • [x] Outline the module deprecation policy: interface removals follow a two-step cycle (deprecated in v1.x, removed no earlier than v2.0) with CHANGELOG and runtime notices.

Configuration schema

Configuration files under etc/ are treated as part of the public contract for self-hosted deployments. The freeze covers file names, array shapes, and default keys used by the bootstrap sequence.

  • [x] Produce a schema index in docs/configuration/overview.md summarising every etc/*.php file, expected keys, and types.
  • [x] Add validation hooks (via composer validate:config script) to detect missing or malformed keys before runtime (task stub).
    • [x] Document the composer validate:config plan and existing runtime / PHPUnit enforcement in docs/configuration/overview.md.
    • [x] Land the Composer script and CI wiring.
  • [x] Forbid silent renames: configuration key migrations must ship shims that read both the old and new keys for one minor release (policy captured in docs/configuration/overview.md).
  • [x] Write the configuration deprecation policy into the upgrade guide, including examples for feature-flagged fallbacks and migration helpers (task stub).

Documentation deliverables for v1.0

Upgrade guide (docs/upgrade/v1.0.md)

  • [x] Draft step-by-step upgrade instructions covering configuration changes, CLI contract updates, and deprecations lifted for v1.0.
  • [x] Include a compatibility matrix showing which OpenSwoole and PHP versions are officially supported.
  • [x] Integrate with the existing static site generator plan (MkDocs) so the guide renders alongside other docs/ content and is published on release day.

Performance benchmarks (docs/benchmarks/)

  • [x] Capture baseline HTTP throughput/latency numbers using the maintained bin/bench/http harness and document the environment configuration.
    • [x] Documented the harness workflow, environment prerequisites, and CI automation in docs/benchmarks/README.md.
  • [x] Schedule the first cold-cache run on dedicated hardware and commit the resulting dataset (task stub).
  • [x] Store raw benchmark results (CSV/JSON) under docs/benchmarks/data/ for reproducibility and graph generation.
    • [x] Established file naming + metadata conventions in docs/benchmarks/README.md.
    • [x] Land the inaugural dataset + artefacts once baseline runs complete (see task stub).
  • [x] Add instructions for regenerating charts using the docs/tools/plot-bench script (Python + matplotlib) and ensure MkDocs can embed the generated images.
    • [x] Implemented docs/tools/plot-bench.py to render charts and Markdown manifests.
    • [x] Documented MkDocs navigation wiring and chart publication workflow.

Starter blueprints (docs/starters/ + README.md overview)

  • [x] Publish opinionated starter templates (REST API, queue worker, WebSocket gateway) with composer create-project snippets in docs/starters/.
  • [x] Reference each blueprint from the main README.md so newcomers can pick a starting point without browsing the full docs site.
  • [x] Provide tooling notes for the static site: enable MkDocs collections to surface starter cards and wire Netlify (or GitHub Pages) deployment so updates go live automatically.

Release readiness tracking

  • [x] Cross-link this document from README.md under the roadmap section so the community can track progress.
  • [x] Review the checklist weekly in milestone syncs and mark completed items to signal stability.
  • [x] Once all freeze tasks are complete, announce the transition to release candidate status on the project discussion board and lock further breaking changes until v2.0 planning begins.