Skip to content

ROADMAP.md

Latest commit

 

History

History
97 lines (82 loc) · 5.42 KB

ROADMAP.md

File metadata and controls

97 lines (82 loc) · 5.42 KB
Raw

Roadmap

Overview

This is a high level roadmap for v6, v7 and v8 - what happens to the classic pipeline and the new Spec attributes and processing pipeline, and when.

The discussion and the tick list of what has shipped are in #1953. This file is the plan; the issue tracks it.

Deprecation rule

A @deprecated marker names the version that removes the thing:

/** @deprecated since 6.11, removed in 8.0 - use ... instead */

Nothing is removed before the version its marker names, and nothing is removed without a marker. Something marked for 8.0 keeps working through v7 unchanged. That is what "no cliff" means here: the marker is the promise.

Timeline

v6

6.5.0 introduced the Spec system as opt-in beta. The remainder of v6 is about completing it and getting people onto it:

  • Spec attributes declared frozen, and Builder declared the stable entry point for every mode. The beta label stays until v7
  • a rector rule set for OpenApi\Attributes -> OpenApi\Spec
  • a seam to contribute pre-built attributes to a Specification before resolution, for framework integrations that do not scan
  • one component: field on every reusable Spec attribute, naming its key in components; the per-type spellings it replaces (schema, parameter, request, securityScheme, and response/header/link/example used as a component key) are marked @deprecated, removed in 8.0, and trigger a runtime deprecation when used
  • docblock annotation support marked @deprecated, removed in 8.0 - the README has said so since 4.8, the code now agrees, and parsing a docblock annotation triggers a runtime deprecation once per run
  • the relocation shims already marked (Pipeline, SourceFinder, Analysers\TokenScanner, Utils\TypeMapper, LegacyTypeResolver) are removed in 7.0
  • Generator::UNDEFINED and Generator::isDefault() stay until 8.0 - every classic custom processor uses them, so they go with classic and not before
  • Result::log(), warnings() and errors() marked @deprecated, removed in 8.0 - the logger set with Builder::setLogger() already receives everything they return, and isValid() stays

Classic attributes, the Generator and the processors are not marked in v6. The replacement is still beta for part of the major, and a stable API is not deprecated in favour of a beta one.

v7

This is where things turn:

  • the beta label comes off the Spec attributes and the hybrid and spec modes
  • default mode switches to hybrid - existing classic projects keep working, routed through the new pipeline via the bridge, with the exception of integrations that build annotation objects directly instead of scanning for them, which the bridge has nothing to scan for
  • all classic code - annotations, attributes and the related pipeline code - is marked @deprecated, removed in 8.0
  • the bridge and mode selection are marked @deprecated, removed in 8.0 - that is Builder::setMode(), the Builder\Mode enum, Console\GenerateInput::$mode and the CLI's -m/--mode option, which go together because there is one pipeline in 8.0 and nothing left to select. The action in v7 is to leave the mode out
  • raw security arrays on spec attributes (['bearerAuth' => []]) are reported and marked for removal in 8.0 - Security\Requirement replaces them, and a rector rule rewrites them
  • everything whose marker says 7.0 is removed
  • nikic/php-parser is raised to ^5.0 - the ^4.19 branch parses no further than PHP 8.3 syntax
  • the Symfony components accept 5.4 and 6.4 or later, dropping 5.0 to 5.3 and 6.0 to 6.3
  • the documentation leads with spec attributes, and classic pages carry a deprecated badge
  • the v7 migration guide states the v8 namespace move below, so nobody meets it as a surprise

The default output version follows the default mode: 3.1.0, where classic defaulted to 3.0.0. Builder::setVersion('3.0.0') or --version 3.0.0 keeps the old output, and the migration guide says so.

v8

classic is removed from the codebase, leaving only the spec pipeline. Annotations are no longer supported at all.

The spec attributes move from OpenApi\Spec to OpenApi\Attributes. With one pipeline left, "Spec" is a mode name that means nothing, and OpenApi\Attributes is the better home. For code written against OpenApi\Spec that is one use line per file, and the rector set does it.

Open: whether OpenApi\Spec stays as deprecated aliases for one major, so the move is optional until v9.

Finding what to remove

Code carries @deprecated with the version that removes it, which is the primary marker and the one tooling understands. Documentation, fixture layout and test-matrix structure cannot carry it - nothing consumes a docblock in a markdown file or a yaml expectation - so those are marked inline with the mode they exist to serve: [classic], [hybrid], or [classic/hybrid] for what serves both. grep -rnE '\[(classic|hybrid)' lists them, and all of it goes when classic does.

The marker names the mode rather than the release on purpose. A thing is [hybrid] for as long as hybrid exists, which stays true whatever happens to this timeline; [v8: drop] would be a claim about a schedule, and would need revisiting if the schedule moved. The two markers do not overlap with @deprecated: if a thing can carry a docblock, it gets @deprecated and not this.