WordPress / WordPress/block-development-examples

Naming conventions: document the directory-naming policy, standardize on plugin.php entry files, fix the scaffold template

Open
#155 0 comments 0 reactions 0 assignees View on GitHub

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-bindings from a Make Core post on Block Bindings in 6.9, and my-first-interactive-block from the Gutenberg Interactivity API quick-start guide (published to the Block Editor Handbook); its name is also the canonical create-block-interactive-template slug, 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
  1. 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.
  2. Standardize on plugin.php:
    • Update the scaffold template to generate plugin.php instead 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).
  3. Record both conventions in CONTRIBUTING.md so 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.