docs: overhaul consumer and maintainer documentation - #95
Open
divyarajmasani wants to merge 1 commit into
Open
Conversation
Audits the docs against the code and closes the gaps a consumer hits
first. No `inc/` behavior changes.
New pages:
- getting-started.md — smallest complete integration: install, a
Registrable service, a module, bootstrap, and Shareable/get_shared().
- upgrading.md — the versioning promise stated against inc/Contracts/,
plus the 1.0.0 -> 1.0.1 Singleton migration.
- troubleshooting.md — symptom -> cause for the framework's exceptions,
_doing_it_wrong() notices, and silent no-ops.
- maintainers.md — environment, checks, test conventions, change
checklist per surface.
- issues/maintainer-documentation-gaps.md — a filled-in task issue for
the maintainer-side gaps: release procedure, SECURITY.md, the wp-env
mount note, a doc-drift guard, and the composer.json script
contradiction. Four open decisions left for the maintainers.
Install path corrected: the package is not on public Packagist
(repo.packagist.org 404s for rtcamp/wp-framework), so the documented
`composer require` could not resolve. README and getting-started now
show the VCS `repositories` entry and a `^1.0` constraint.
Accuracy fixes:
- architecture.md — the load-loop snippet claimed
`array_unique( $classes )`; Loader::load() uses a `$seen` map.
- abstracts.md — the `option_page_capability_{group}` filter is
unconditional; a lowered capability is the case where it matters, not
the trigger. AbstractRESTController throws \LogicException, not a bare
\Exception.
- contracts.md, architecture.md — Singleton behavior corrected to match
the 1.0.1 fix: the re-entrancy guard and the shared subclass slot.
Coverage: a worked WP-CLI example (CLICommand was the only contract
without one); AssetLoader path safety and handle helpers; the component
and template hook tables; the Cache, FeatureSelector, and Timer APIs;
README requirements, a quick-look snippet, and the missing utilities.
Contributor workflow: CONTRIBUTING and README route to `composer lint`,
`composer analyse`, `npm run test:php` — `composer check`/`test` run
PHPUnit on the host and need a separate WordPress test suite.
AGENTS.md and .github/instructions/ gain AbstractFeature, which was
missing from the class inventory.
All relative links verified to resolve.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
divyarajmasani
commented
Sep 3, 2026
| ```bash | ||
| composer lint | ||
| composer analyse | ||
| npm run test:php |
Author
There was a problem hiding this comment.
The test command, may need some confirmation and consolidation. If we are planning to only support the wp-env lead test setup we can just update the composer script to run this npm script.
divyarajmasani
commented
Sep 3, 2026
Comment on lines
+24
to
+27
| - PHP 8.2+ | ||
| - WordPress 6.5+ | ||
| - Composer | ||
| - The OpenSSL PHP extension when using `Encryptor` |
Author
There was a problem hiding this comment.
Clear dependencies, we may want to amend these, but need to keep at the top.
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
1 participant
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 this PR does
Overhauls the framework documentation so implementors can integrate the library from a complete example and maintainers have an explicit development workflow. It also audits the existing reference material against the shipped implementation, correcting stale behavior and filling the highest-impact API, installation, upgrade, and troubleshooting gaps.
Closes
Closes #92
Changes
Singleton,Loader,AbstractRESTController, andAbstractSettingsPagebehavior to match the implementation.composer checkworkflow with the actual PHPCS, PHPStan, and wp-env test commands.How I verified
The branch changes documentation and instruction files only; no
inc/runtime file is modified.Acceptance criteria
Runtime behavior
Code quality
Housekeeping
CHANGELOG.mdentry added under## [Unreleased].Reviewer notes
inc/Contracts/as the explicitly documented contract surface while treating removal of a public class or method as a major consumer impact.AI assistance
I gathered the initial requirements and defined the documentation direction. AI was used to audit the repository against those requirements, expand the identified topics, and assist with drafting and refining the documentation.
Screenshots / terminal output
Not applicable; documentation-only change.