docs: strip version-history annotations across PHP, TS, and Markdown - #426
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What it does
Removes every version-history annotation from the documentation surface —
@since 0.xdocblock 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 thedocs/README.mdconventions 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
@sincetrail 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
@since X.Y.Zlines including multi-line change descriptions and their continuation lines; inline/** … @since X */tags;_Since 0.8.6._table-cell labels;// since 0.xcode-comment stamps.@since(the 11Desktop_Mode_*_Fileclasses, the two extension base classes, one REST permission callback) got a one-line functional description instead of an empty shell.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.docs/migration-*.mdand 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:
Plus a manual smoke test: plugin activates in wp-env,
desktop-mode/v1REST 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: