docs(docs): generate the version compatibility table from the manifests - #232
Merged
Merged
Conversation
The README told a consumer how to install each package and nothing about which versions go together, so the only way to learn that the kit is one set was to get it wrong. The packages depend on each other through dependencies rather than peers, so a mismatched set does not fail: it resolves a second nested copy and splits ui-utils' module-level singletons. The section is generated from the package manifests rather than written, so it cannot drift from the versions it describes. Prose whose truth rests on a manifest fact is emitted only while the manifests still support it: the coherence rationale disappears if an intra-kit peer range ever appears, and the note explaining ui-utils' major gap disappears if the gap closes. The changesets version script regenerates the section, so a release PR carries the updated table, and --check in CI fails if the two ever disagree.
✅ Deploy Preview for openzeppelin-ui ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
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 subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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.
Why, given I argued against it
My objection was that a hand-maintained matrix drifts and that #229 already checks the set
mechanically. The first half is answered outright: this table is generated from the package
manifests, so it cannot drift. The second half was never a real objection —
check-peersonly helps someone who already knows to run it, and a reader opening the repo had nothing
telling them the kit is one set. Both things can be true, so it is written.
What is in it
A generated
## Version compatibilitysection in the root README, placed immediately after## Installation— which lists apnpm addper package and says nothing about versions, soit is exactly where the question arises and where the answer was missing.
Everything rendered comes out of
packages/*/package.json:@openzeppelin/ui-types3.5.2@openzeppelin/ui-utils4.0.1ui-types@openzeppelin/ui-components3.9.0ui-types,ui-utils@openzeppelin/ui-storage1.2.5ui-types,ui-utils@openzeppelin/ui-react3.3.2ui-components,ui-types,ui-utils@openzeppelin/ui-renderer3.4.2ui-components,ui-react,ui-types,ui-utilsThe set is not hand-picked: it is the connected component of the intra-kit dependency graph
containing
ui-components.ui-stylesandui-clicarry no intra-kit edges, so they cannotbe split by a version mismatch and are left out rather than listed with nothing to say. That
also means the table includes
ui-rendererandui-storage, which are subject to the samesplitting problem as the four packages I was asked to cover.
Alongside the table, three short subsections:
dependencies,not
peerDependencies(there is not one intra-kit peer range in the kit), so a mismatchresolves instead of failing:
ui-componentsquietly gets a second nestedui-utils. Twocopies of
ui-utilsis the case that bites, becauseappConfigServiceis a single instanceand
loggeris agetInstance(), so the copy your app did not initialise answers withdefaults and never throws. Two copies of
ui-typesgive TS2322/TS2345 instead. It ends withthe command to check the edges rather than take my word for them:
npm view @openzeppelin/ui-components@3.9.0 dependencies --json | grep '@openzeppelin'mismatch.
ui-utilsleads at 4.x because it removed WalletConnect in feat(cli): stop scaffolding WalletConnect configuration #210, breaking for itsown consumers and a dependency bump for everyone else. Explicitly: do not try to line the
majors up.
oz-ui-dev check-peers, so the doc says what toinstall and the tool says what actually resolved. They reinforce rather than compete.
Claims cannot outlive their evidence
The generator emits conditional prose only while the manifests still support it, which is the
part that makes a generated doc better than a written one rather than just cheaper. Verified
by mutating manifests and regenerating:
ui-utils→3.9.9(majors align)ui-utils4.x-vs-3.x paragraph disappears; the majors section stays, correctly, becauseui-storageis still 1.xui-utils→5.0.0peerDependenciesentryThe release loop closes
A CI drift check alone would fail every
chore(release): version packagesPR, since the botbumps versions and would not regenerate. So the root
versionscript — which is whatchangesets/actionruns — now regenerates as well:Simulated end to end by bumping
ui-utilsto5.0.0: guard fails (exit 1), the versionscript's regenerate runs, guard passes (exit 0). A release PR therefore carries the updated
table on its own.
Checks
Exit codes captured directly, not read through a pipe:
pnpm buildpnpm testpnpm typecheckpnpm lintpnpm format:checkpnpm check-compatibilityREADME matches the package manifestspnpm check-licensespnpm check-changesetsThe generated block is also Prettier-stable — the generator pads table columns the way
Prettier does, so
prettier --write README.mdleaves the block byte-identical and cannotfight the generator. (README.md as a whole does not pass
prettier --checkonmaineither;that is pre-existing and I have not touched it.)
No changeset. Nothing published changes — the root README, root scripts and CI are not in
any package's
filesarray, so no package tarball is affected.Judgement call worth flagging
I considered injecting the same generated block into each package README, since npm shows
those and never shows the root one, and that is where a consumer literally meets a package. I
did not, for two reasons: it would force a release of six packages for a documentation change,
and it would put six competing copies of a claim about the relationship between packages
into the packages themselves. The cross-package table belongs in the one cross-package place.
Say so if you would rather have it in the package READMEs too — the generator already has the
package list and the marker machinery, so it is a small change.