Documentation: updating lib/PHP README.md

[ramonjd]

What?

The documentation in /lib/README.md, while full of great advice, does not reflect the common reality.

Of particular note are the guidelines relating to naming conventions and avoiding naming conflicts with Core. They have led to some confusion. See: #51959 (comment)

This PR, by no means comprehensive, rejigs things a bit.

Why?

It's hard to be prescriptive when it comes to naming conventions in Gutenberg. Rather, we can emphasize best practice guidelines and 🤞🏻

Testing Instructions

Do the changes make sense? Are they helpful?
Any typos?

[github-actions]

This pull request has changed or added PHP files. Please confirm whether these changes need to be synced to WordPress Core, and therefore featured in the next release of WordPress.

If so, it is recommended to create a new Trac ticket and submit a pull request to the WordPress Core Github repository soon after this pull request is merged.

If you're unsure, you can always ask for help in the #core-editor channel in WordPress Slack.

Thank you! ❤️

View changed files

❔ lib/README.md

[github-actions]

Flaky tests detected in bddfc4b.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/5851738762
📝 Reported issues:

• [Flaky Test] should partially select with shift + click (@webkit) #53524 in /test/e2e/specs/editor/various/multi-block-selection.spec.js

[andrewserong]

This is great @ramonjd, I love the more descriptive introductions and expanded language — it feels like it's got a more welcoming and guided tone for newer contributors in this update 👍

Since there's quite a lot of changes I found it easier to read and check for flow by looking at the direct file: https://github.com/WordPress/gutenberg/blob/bddfc4b4a0952cb68f7552e87477b2e0643540fa/lib/README.md

This reads very nicely to me. I just left a comment about one sentence, but feel free to disregard, since it's likely subjective!

It might be worth getting another pair of 👀 to double-check the approach in case others have feedback, but this looks like a good approach to me! ✨

[andrewserong]

The wording here feels slightly awkward to me. Rather than caveat, can we be explicit that there must not be a duplicate? Perhaps something like:

When doing so, care must be taken to ensure that no duplicate declarations to create functions or classes exist between Gutenberg and WordPress core code. A quick codebase search will also help you know if your new names are unique.

I think that should bridge the sentence above and the sentence below? Feel free to disregard this comment, though!

[ramonjd]

Thank you for proof reading this. I have shamelessly plagiarized your example sentence. Much better. 🙇🏻

[oandregal]

This is more close to reality than before. Thank you!

[noisysocks]

Nice!

[gziolo]

Thank you so much for improving the documentation that greatly reflects how the process has evolved 👏