Skip to content

Commit 0ce31a2

Browse files
committed
docs: say that anyone can add a registry item, and stop hand-editing a generated file
Two defects, one of them the reason 64 stale entries survived in registry.json. The checklist told contributors to add their item to registry/registry.json. That file is generated from the item directories, so an entry added by hand survives until the next regeneration and then vanishes, and one left behind for a directory that no longer exists is worse: hyperframes add resolves the name and then fails on missing files. Both CONTRIBUTING.md and the agent-facing skill reference now run the generator instead. Nothing said contribution was maintainer-only, but nothing said it was not either, and two steps do need assets an outside contributor has no reason to install. Those are now named in a table with what happens if you do not have them, matching how the preview image was already handled. The search index is the new one: the model behind it is a 32 MB opt-in for search, not a build dependency.
1 parent 85a409d commit 0ce31a2

3 files changed

Lines changed: 36 additions & 7 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 29 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -91,11 +91,36 @@ Blocks don't need `demo.html` — they are already standalone compositions.
9191

9292
### Checklist for new items
9393

94+
**Anyone can add an item.** Nothing here needs commit access, and the two steps
95+
that do need something a contributor may not have are handled by a maintainer
96+
before merge, listed at the end.
97+
9498
1. Create `registry/<blocks|components>/<name>/registry-item.json` following the [schema](packages/core/schemas/registry-item.json)
95-
2. Add the item to `registry/registry.json`
96-
3. For components: include a `demo.html`
97-
4. Run `npx hyperframes lint` and `npx hyperframes validate` on your HTML
98-
5. Test the install flow: `hyperframes add <name> --dir /tmp/test-project`
99+
2. For components: include a `demo.html`
100+
3. Run `npx hyperframes lint` and `npx hyperframes validate` on your HTML
101+
4. Test the install flow: `hyperframes add <name> --dir /tmp/test-project`
102+
5. Regenerate the manifest: `npx tsx scripts/generate-registry-items.ts`
103+
104+
`registry/registry.json` is generated from the item directories, so edit it with
105+
that script rather than by hand. An entry added by hand survives until the next
106+
regeneration and then disappears; entries left behind for directories that no
107+
longer exist are worse, because `hyperframes add <name>` resolves the name and
108+
then fails on missing files.
109+
110+
### What a maintainer finishes for you
111+
112+
Two things need assets an outside contributor is not expected to install. Open
113+
the pull request without them and say so; neither blocks review.
114+
115+
| Thing | If you have it | If you do not |
116+
| ----------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------- |
117+
| The search index (`registry/catalog-artifact/`) | The pre-commit hook rebuilds and stages it | The hook skips, CI names the gap, a maintainer regenerates before merge |
118+
| The catalog preview image | Internal contributors run `scripts/upload-docs-images.sh` | Attach the preview MP4 to the PR instead |
119+
120+
The search index needs a 32 MB embedding model, which is an opt-in for catalog
121+
search rather than a build dependency. Until it is regenerated your item is
122+
findable by word search and not by meaning, which is the same state as any item
123+
published since a user last refreshed their copy.
99124

100125
### Auto-generated docs
101126

‎skills-manifest.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@
4242
"files": 3
4343
},
4444
"hyperframes-registry": {
45-
"hash": "21dc40bf1261b90d",
45+
"hash": "eca45f795c2ff093",
4646
"files": 10
4747
},
4848
"media-use": {

‎skills/hyperframes-registry/references/contributing.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -132,8 +132,12 @@ git checkout -b feat/registry-{name}
132132
# 2. Format HTML
133133
npx oxfmt registry/{kind}/{name}/*.html
134134

135-
# 3. Update registry/registry.json — add entry to the "items" array:
136-
# { "name": "{name}", "type": "hyperframes:block" } (or "hyperframes:component")
135+
# 3. Regenerate registry/registry.json from the item directories.
136+
# Do not hand-edit it: an entry added by hand survives until the next
137+
# regeneration and then vanishes, and one left behind for a directory that
138+
# no longer exists is worse, because `hyperframes add <name>` resolves the
139+
# name and then fails on missing files.
140+
npx tsx scripts/generate-registry-items.ts
137141

138142
# 4. Generate catalog docs page
139143
npx tsx scripts/generate-catalog-pages.ts

0 commit comments

Comments
 (0)