Skip to content

docs: rename annotations-reference to attributes-reference#800

Merged
oojacoboo merged 2 commits intothecodingmachine:masterfrom
oojacoboo:docs/rename-annotations-to-attributes-reference
Apr 22, 2026
Merged

docs: rename annotations-reference to attributes-reference#800
oojacoboo merged 2 commits intothecodingmachine:masterfrom
oojacoboo:docs/rename-annotations-to-attributes-reference

Conversation

@oojacoboo
Copy link
Copy Markdown
Collaborator

@oojacoboo oojacoboo commented Apr 22, 2026

Stacked on top of #799 (the anchor/prose cleanup PR). Please merge #799 first, then this one.

Summary

Doctrine annotation support was dropped in #677; the page's body has been calling these "attributes" for a long time (the title is already Attributes reference). This PR brings the filename and URL slug in line so the whole stack uses consistent terminology, and cuts a new docs version (8.2.0) to capture the current state of docs/ as a released snapshot.

What changed

Rename

  • docs/annotations-reference.mdattributes-reference.md (plus frontmatter id and sidebars.json entry).
  • Incoming link in docs/authentication-authorization.mdx updated.
  • Anchor fragments in docs/CHANGELOG.md and docs/migrating.md were already stale (sections were renamed from ## @Input annotation## #[Input] long ago); repointed them at the current slugs (#input, #field, #hideifunauthorized) and stripped the dead -annotation suffix.

New docs version: 8.2.0

Generated via yarn docusaurus docs:version 8.2.0. This captures the current state of docs/ — the rename, the prose cleanup, and already-merged-to-master but unreleased features like #[EnumValue] (#793) — as a new versioned release. 8.2.0 becomes the new "latest" in versions.json, so /docs/* now serves from it.

Minor docs-version snapshots are established convention in this project (6.1, 4.3, 4.2, 4.1 are all on record), so cutting 8.2.0 alongside this rename does not break norms.

versioned_docs/version-8.0.0/ is untouched — it remains the frozen v8.0.0 release snapshot and diffs to zero against master.

Backwards compatibility

Added @docusaurus/plugin-client-redirects (pinned to the existing 2.4.3 line) with a single rule: /docs/annotations-reference/docs/attributes-reference. External inbound links keep working; the generated redirect uses <meta http-equiv="refresh"> + a JS fallback that preserves the URL fragment (so #input-annotation style bookmarks still land on the same place they would have before).

Remaining prose cleanup

While touching this area, also fixed a few stale "annotation" prose references that the Doctrine removal missed:

  • custom-types.mdx — "in the following annotations:" → "in the following attributes:"
  • semver.md — "mainly through its annotations" / "developing custom annotations" → "attributes"
  • argument-resolving.md — stale @Autowire annotation and related wording in the parameter-middleware example

Intentionally left alone: doctrine-annotations-attributes.mdx (migration guide), real PHP symbol names (TheCodingMachine\GraphQLite\Annotations\*, MiddlewareAnnotations, ParameterAnnotations), and the annotations parameter of #[SourceField]/#[MagicField] (actual PHP parameter name in source).

URLs after merge

URL Resolves to
/docs/annotations-reference redirects to /docs/attributes-reference
/docs/attributes-reference v8.2.0 (new latest)
/docs/8.0.0/annotations-reference v8.0.0 snapshot, frozen, unchanged
/docs/next/attributes-reference docs/ preview

Review note

The second commit on this PR (revert v8.0.0 edits and cut v8.2.0 snapshot instead) corrects a first-pass approach that mistakenly edited versioned_docs/version-8.0.0/ to keep the redirect target valid. That was revisionist — frozen snapshots shouldn't be modified for unreleased terminology. The proper fix is to cut a new version, which is what this PR now does. Happy to squash on merge if preferred.

Test plan

  • yarn build passes cleanly (no unresolved markdown links).
  • build/docs/annotations-reference/index.html contains a <meta http-equiv="refresh"> pointing at /docs/attributes-reference, plus a JS fallback that appends window.location.hash.
  • build/docs/attributes-reference.html generated from v8.2.0.
  • build/docs/8.0.0/annotations-reference.html still generated from the unchanged v8.0.0 snapshot.
  • git diff origin/master -- website/versioned_docs/version-8.0.0/ website/versioned_sidebars/version-8.0.0-sidebars.json returns empty.
  • After merge, smoke-test the deployed site: /docs/annotations-reference redirects to /docs/attributes-reference; /docs/annotations-reference#field preserves the fragment.

@codecov-commenter
Copy link
Copy Markdown

codecov-commenter commented Apr 22, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.84%. Comparing base (53f9d49) to head (a947224).
⚠️ Report is 151 commits behind head on master.

Additional details and impacted files
@@             Coverage Diff              @@
##             master     #800      +/-   ##
============================================
- Coverage     95.72%   94.84%   -0.89%     
- Complexity     1773     1869      +96     
============================================
  Files           154      175      +21     
  Lines          4586     5079     +493     
============================================
+ Hits           4390     4817     +427     
- Misses          196      262      +66     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Doctrine annotation support was dropped in thecodingmachine#677; the page's body has
been calling these "attributes" for a long time. Bring the filename
and URL slug in line so the whole stack uses consistent terminology.

What changed
- website/docs/annotations-reference.md → attributes-reference.md
  (plus frontmatter `id` and sidebars.json entry)
- versioned_docs/version-8.0.0/ gets the same rename since 8.0.0 is
  the current stable release served at `/docs/annotations-reference`.
  Older versioned_docs are frozen snapshots and are left untouched.
- versioned_sidebars/version-8.0.0-sidebars.json updated to match.
- Incoming link in authentication-authorization.mdx updated (both
  the `next` and v8.0.0 copies).
- CHANGELOG.md and migrating.md link paths updated (both copies).
  Anchor fragments were already stale (sections were renamed from
  `## @input annotation` → `## #[Input]` long ago); repointed them at
  the current slugs where the anchor identifies the attribute
  unambiguously, and stripped the dead `-annotation` suffix.

Backwards compatibility
- Added `@docusaurus/plugin-client-redirects` (pinned to the existing
  2.4.3 line) with a single rule: `/docs/annotations-reference` →
  `/docs/attributes-reference`. External inbound links keep working
  (meta-refresh + JS redirect, preserves the URL fragment).

Remaining prose cleanup
While touching this area, also fixed a few stale "annotation" prose
references that the Doctrine removal missed:
- custom-types.mdx: "in the following annotations:" → "attributes:"
- semver.md: "through its annotations"/"custom annotations" → attributes
- argument-resolving.md: stale `@Autowire annotation` and related
  wording in the parameter-middleware example

Verified via `yarn build`: site compiles clean, redirect HTML emitted
at build/docs/annotations-reference/index.html pointing at the new
canonical URL.
Follow-up to review feedback: v8.0.0 is a frozen release snapshot and
shouldn't be edited to reflect unreleased terminology. Restore all
v8.0.0 versioned_docs files to their state at release time (matches
origin/master exactly).

Instead, cut a new v8.2.0 docs snapshot via `yarn docusaurus docs:version
8.2.0`. That captures the current `docs/` state — including the rename,
the prose cleanup, and unreleased features like #[EnumValue] (thecodingmachine#793) —
as a new versioned release. 8.2.0 becomes the new "latest" (first in
versions.json), so `/docs/*` now serves from it and the redirect
target `/docs/attributes-reference` is valid.

Result:
- /docs/annotations-reference → redirects to /docs/attributes-reference
- /docs/attributes-reference → v8.2.0 (new latest)
- /docs/8.0.0/annotations-reference → v8.0.0 snapshot, frozen, unchanged
- /docs/next/attributes-reference → docs/ preview

Minor docs-version snapshots are established convention in this
project (6.1, 4.3, 4.2, 4.1 are all on record), so cutting 8.2.0
alongside this rename does not break norms.

Build verified: `yarn build` passes; redirect HTML emitted at
build/docs/annotations-reference/index.html; v8.0.0 snapshot diffs
to origin/master as zero.
@oojacoboo oojacoboo force-pushed the docs/rename-annotations-to-attributes-reference branch from 9a14b63 to a947224 Compare April 22, 2026 00:59
@oojacoboo oojacoboo merged commit 49e2065 into thecodingmachine:master Apr 22, 2026
13 checks passed
@oojacoboo oojacoboo deleted the docs/rename-annotations-to-attributes-reference branch April 22, 2026 01:02
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