Skip to content

docs: strip version-history annotations across PHP, TS, and Markdown - #426

Merged
epeicher merged 2 commits into
trunkfrom
deskmod-55-clean-docs
Jul 28, 2026
Merged

docs: strip version-history annotations across PHP, TS, and Markdown#426
epeicher merged 2 commits into
trunkfrom
deskmod-55-clean-docs

Conversation

@epeicher

@epeicher epeicher commented Jul 27, 2026

Copy link
Copy Markdown
Collaborator

What it does

Removes every version-history annotation from the documentation surface — @since 0.x docblock tags, Stable *(0.8.3)* status stamps, and "(since 0.8.4)" / "as of 0.9.1" / "added in 0.8.0" / "fixed in 0.8.5" prose asides — across PHP, TS, and Markdown. 774 files, −6,081 lines. Docs and docblocks now describe what the current release does, not when each surface landed.

Also adds the rule to AGENTS.md (and the docs/README.md conventions list) so the stamps don't creep back in: document functionality, not when it was added. Status labels stay (Stable, Experimental, @deprecated) — bare, with no version attached.

Rationale

Approaching 1.0, the accumulated @since trail is noise: it burns context for LLMs and reading time for humans, and git history already answers "when did this land" with more precision. Version stamps also leak into GitHub heading anchors, so renaming a status breaks deep links (several were already broken for exactly this reason).

Implementation

  • Pure removals: @since X.Y.Z lines including multi-line change descriptions and their continuation lines; inline /** … @since X */ tags; _Since 0.8.6._ table-cell labels; // since 0.x code-comment stamps.
  • Rewording, not deletion, where the sentence carries real content: "Since 0.8.5 the endpoint caches…" → "The endpoint caches…". Kept semantics, dropped the when.
  • Docblocks whose only content was @since (the 11 Desktop_Mode_*_File classes, the two extension base classes, one REST permission callback) got a one-line functional description instead of an empty shell.
  • Heading anchors: 57 cross-references remapped to the new slugs; 8 links that were already dead at trunk (hand-written with wrong hyphen counts, or pointing at -since- anchors) repaired against the current headings; 2 links to sections that don't exist (wp.desktop.confirm, <wpd-save-status>) unlinked to plain code text.
  • Deliberately kept: docs/migration-*.md and index entries pointing at them (version-anchored by design), the "architecture-0.8.1" refactor name those docs define, WordPress-core version references ("since 4.5", "pre-6.9 sites"), and numeric values that merely look like versions (opacities, clamps).

Testing instructions

Behavior is untouched — the diff is comments, docs, and docblock text only. Verified with the full battery:

npm run build && npm run lint && npm run typecheck && npm run test:js   # 2,297 tests green
npm run env:start:tests && npm run test:php                            # 1,609 tests, 4,146 assertions green

Plus a manual smoke test: plugin activates in wp-env, desktop-mode/v1 REST namespace registers, and the desktop shell boots and renders the Dashboard window with no PHP or console errors.

To confirm no stragglers, this grep should only hit docs/migration-* and the AGENTS.md rule itself:

grep -rnE '@since|[Ss]ince [0-9]+\.[0-9]' --include='*.php' --include='*.ts' --include='*.md' . | grep -v node_modules
Open WordPress Playground Preview

epeicher added 2 commits July 27, 2026 13:50
Remove @SInCE docblock tags, Stable/Experimental version stamps,
and 'since / as of / added in / fixed in 0.x' asides everywhere —
the docs now describe what the current release does, not when each
surface landed. Docblocks whose only content was @SInCE get a real
one-line description instead. Markdown heading anchors that embedded
old status text are remapped, and a handful of already-dead
version-flavored links are repaired or unlinked.

Deliberate keeps: docs/migration-*.md (version-anchored by design),
the architecture-0.8.1 refactor name, WordPress-core version
references, and numeric values that merely look like versions.

Adds the rule to AGENTS.md so version stamps don't creep back in.
Resolves conflicts from the editor-preview (#398) and corner-radius
(#422) features by keeping trunk's new content with its version
stamps stripped, per the new AGENTS.md rule: new @SInCE tags in
window-links.php, editor-preview/*, types.ts, window/index.ts,
hooks.ts, and the new hooks-reference / javascript-reference /
bridge-protocol / api-index sections all land clean.

Also repairs three headings in bridge-protocol.md that the original
cleanup had accidentally glued to their following paragraph, and the
one cross-reference that pointed at a glued slug.
@epeicher epeicher self-assigned this Jul 28, 2026

@AllTerrainDeveloper AllTerrainDeveloper left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wonderful

@epeicher
epeicher merged commit 1b6425f into trunk Jul 28, 2026
6 checks passed
@epeicher
epeicher deleted the deskmod-55-clean-docs branch July 28, 2026 08:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants