WordPress / WordPress/block-development-examples
Naming conventions: document the directory-naming policy, standardize on plugin.php entry files, fix the scaffold template
Open
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 334
- Forks
- 52
- PR merge metrics
- No merged PRs in 30d
Description
Problem
Two naming conventions have drifted, and the scaffold template contradicts one of them:
- Directory names: 27 example dirs follow
<name>-<6-hex-hash>, but three don't:editor-bindings,my-first-interactive-block,post-meta-testimonial. Renaming them is not the right fix — GitHub doesn't redirect renamed tree paths, and there are live inbound links:editor-bindingsfrom a Make Core post on Block Bindings in 6.9, andmy-first-interactive-blockfrom the Gutenberg Interactivity API quick-start guide (published to the Block Editor Handbook); its name is also the canonicalcreate-block-interactive-templateslug, which is the point of the example. - Entry files: 27 plugins use
plugin.php; 3 use a slug-named file (copyright-date-block-09aac3/copyright-date-block.php,post-meta-testimonial/post-meta-testimonial.php,server-side-render-block-d26119/server-side-render-block-d26119.php). Meanwhile the scaffold template (templates/block-examples/templates/plugin/$slug.php.mustache) generates slug-named files — so every new example is born breaking the de-facto standard.
Proposed fix
- No directory renames. Document the policy in
CONTRIBUTING.md(introduced by #149): the-<hash>suffix is legacy; new examples need a unique, descriptive slug, hash optional. The three existing non-hash dirs are grandfathered. - Standardize on
plugin.php:- Update the scaffold template to generate
plugin.phpinstead of$slug.php. - Rename the 3 outlier entry files to
plugin.php(this changes their plugin basename, which deactivates the plugin for anyone upgrading an installed zip in place — acceptable for a teaching repo, worth a line in the release notes).
- Update the scaffold template to generate
- Record both conventions in
CONTRIBUTING.mdso the next example follows them without archaeology.
Out of scope
- Text domains, block namespaces, and header normalization (#150).
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Read CONTRIBUTING.md and inspect templates/block-examples/templates/plugin/$slug.php.mustache first. Locate the three named slug-based entry files and update the documented directory and entry-file conventions, ensuring the scaffold generates plugin.php and all three outliers use that name; the existing directory names should remain unchanged.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- documentation, tooling
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100