feat(release): resolve @since version placeholders at release time

[faisalahammad]

Closes #151

New SCF APIs can now be written as @since SCF {NEXT_MAJOR_VERSION} instead of guessing the version number. composer prepare-release replaces the placeholder with the real release version after the maintainer enters and confirms it, so annotations stay correct when a release slips and the version changes.

Since_Resolver in bin/class-scf-since-resolver.php scans includes, src and assets/src for PHP, JS, JSX, TS and TSX files. It only rewrites the token inside an @since annotation and normalises the result to @since SCF <version>, so legacy @since ACF ... tags, versions that are already resolved, and an unrelated placeholder in a string literal are left untouched. The resolver returns the list of changed files and fails loudly if a write does not go through.

The release script calls it right after the changelog confirmation, then regenerates the docs and commits only the resolved source files plus docs/code-reference and docs/bin/manifest.json. The commit is skipped when nothing changed.

Contributor docs now describe the convention in docs/contributing/index.md, and docs/contributing/releases.md documents the release step.

Two limits worth knowing: pro/ is not scanned because it has no @since tags today, and the docs generator only parses PHP under includes, so a placeholder in src/ or in JS is rewritten in source but does not show up in the generated code reference.

Testing instructions

• composer test:php (the new Test_SCF_Since_Resolver covers placeholder replacement, existing ACF and SCF tags staying put, a bare placeholder outside an annotation being ignored, unsupported file types, and the no-op case)
• vendor/bin/phpunit --filter Test_SCF_Since_Resolver tests/php
• composer lint:php
• npm run test:unit

Manual check: copy the plugin to a temp directory, add @since SCF {NEXT_MAJOR_VERSION} to a PHP file under includes and a JS file under assets/src, then run the resolver against that tree. The new annotations become @since SCF <version>, and existing @since ACF 6.1 and @since SCF 6.9.5 tags are unchanged.

bin/ and tests/ are not part of the release zip, so this change has no effect on the distributed plugin. E2E tests were not run because nothing in the shipped runtime path changed.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props faisalahammad, priethor.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[faisalahammad]

CI Fix Summary

The failing E2E checks were not caused by this PR. WordPress trunk renamed the editor preview menu item from "Preview in new tab" to "Preview (opens in a new tab)". The pinned test helper @wordpress/e2e-test-utils-playwright (1.32.0) looks for the old exact label, so editor.openPreviewPage() timed out.

This is a trunk wide breakage that hits every branch, and it is already fixed on the fix/384-export-post-meta branch (PR #544).

Change

• tests/e2e/fixtures.js: the local editor.openPreviewPage override stopped calling the upstream helper when the "View" button is visible. It now clicks the View button (or Preview on WP 6.2) itself and matches the menu item with getByRole('menuitem', { name: /Preview.*new tab/i }), so both the old and the new label match.

Test only change. No plugin runtime code touched.

Errors fixed

TimeoutError: browserContext.waitForEvent: Timeout 10000ms exceeded while waiting for event "page" at Editor.openPreviewPage (preview.ts:27), 39 test cases across WP trunk shards 2/4, 3/4 and 4/4.

Validation

• npx wp-scripts lint-js and Prettier clean
• npm run test:unit pass
• composer test:php 2948 tests, 22755 assertions, OK
• Targeted PHPStan and PHPCS on changed files pass
• No E2E run locally. CI will confirm the trunk shards on this push.

Refs #547