Components: add "Naming conventions" section #63714

ciampo · 2024-07-18T15:26:03Z

What?

Tweak the contributing guidelines, updating a few out of date parts and adding a new "Naming Conventions" section based on the conversation happening in #63242

Why?

As we introduce more compound components in the package, we need a recommended naming conventions for both monolithic and compound components going forward.

ciampo · 2024-07-18T15:31:38Z

@WordPress/gutenberg-components I took an initial stab at updating the contributing guidelines.

Also cc @diegohaz in case you have any feedback.

github-actions · 2024-07-18T15:31:53Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: ciampo <[email protected]>
Co-authored-by: tyxla <[email protected]>
Co-authored-by: mirka <[email protected]>
Co-authored-by: DaniGuardiola <[email protected]>
Co-authored-by: diegohaz <[email protected]>
Co-authored-by: youknowriad <[email protected]>
Co-authored-by: ntsekouras <[email protected]>
Co-authored-by: aaronrobertshaw <[email protected]>
Co-authored-by: noisysocks <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

ciampo · 2024-07-18T15:33:45Z

packages/components/CONTRIBUTING.md

- [README example](#README-example)
- [Folder structure](#folder-structure)
- [Component versioning](#component-versioning)
+-   [Introducing new components](#introducing-new-components)


My IDE insists on auto-formatting this file. I've put all the auto-formatting changes in one single commit, but if you think they're too distracting / they don't belong to this PR I'm happy to remove and potentially apply them in a separate PR.

👍

It's also easier to review the PR with white-spacing disabled:

ciampo · 2024-07-18T15:34:44Z

packages/components/CONTRIBUTING.md

+When adding new components or new props to existing components, it's recommended to create a [private version](/packages/private-apis/README.md)) of the component until the changes are stable enough to be exposed as part of the public API.

 ### Learn more

- [How to preserve backward compatibility for a React Component](/docs/contributors/code/backward-compatibility.md#how-to-preserve-backward-compatibility-for-a-react-component)
- [Experimental and Unstable APIs](/docs/contributors/code/coding-guidelines.md#experimental-and-unstable-apis)
- [Deprecating styles](#deprecating-styles)
+-   [How to preserve backward compatibility for a React Component](/docs/contributors/code/backward-compatibility.md#how-to-preserve-backward-compatibility-for-a-react-component)
+-   [Experimental and Unstable APIs](/docs/contributors/code/coding-guidelines.md#legacy-experimental-apis-plugin-only-apis-and-private-apis)
+-   [Deprecating styles](#deprecating-styles)


I've updated this section to reflect the new "private APIs" policy

packages/components/CONTRIBUTING.md

tyxla

This is more or less looking good, but still has some debatable elements (the Component.Root dot notation mostly) that still needs a stronger consensus in the #63242 discussion at this time.

packages/components/CONTRIBUTING.md

DaniGuardiola

Looks good so far, though it seems like we're switching to an "overloaded" API?

mirka · 2024-07-30T18:54:00Z

@DaniGuardiola and I were discussing some potential TypeScript problems with overloading when forwardRef() is involved.

It's a bit finicky where you need to place your JSDocs and .displayNames, but I can confirm that this approach with Object.assign is working as expected for IntelliSense and the Storybook docgen.

ciampo · 2024-07-31T15:36:09Z

I've updated the PR suggesting the "overloaded" naming convention and refreshing the code examples.

Could y'all take a new look?

(as I'm going to be AFK for a week, feel free to push updates and/or merge in case in my absence)

tyxla

This is looking great 👍

I've left some minor things mostly, I'll let @mirka and @DaniGuardiola take a look and share their feedback before we ship it.

packages/components/CONTRIBUTING.md

tyxla · 2024-08-01T11:01:47Z

packages/components/CONTRIBUTING.md

+const Context = createContext();
+
+/** The top-level component's JSDoc. */
+export const Component = Object.assign(


Could be a good opportunity to explain the purpose behind using Object.assign() here.

Yes, and it might be useful to state what exactly we need to look for:

When consuming the component/subcomponent, the JSDocs must appear correctly in IntelliSense.

The main component JSDoc must appear in the Storybook docs page.

The component/subcomponent prop types must appear correctly in the Storybook props table.

Added a couple of paragraphs explaining requirements and related recommended best practices: 432635b

This way the only comments in the code are related to the JSDocs

packages/components/CONTRIBUTING.md

tyxla · 2024-08-01T11:05:41Z

packages/components/CONTRIBUTING.md

- [README example](#README-example)
- [Folder structure](#folder-structure)
- [Component versioning](#component-versioning)
+-   [Introducing new components](#introducing-new-components)


👍

It's also easier to review the PR with white-spacing disabled:

mirka

Thank you for the update! I had a few notes on top of @tyxla's review, but otherwise this looks great 👍

packages/components/CONTRIBUTING.md

…nt best practices

…monolithic components

…practices

ciampo · 2024-08-08T07:37:13Z

All feedback should be addressed

tyxla

Good to go from my perspective. Thanks @ciampo 🚀

packages/components/CONTRIBUTING.md

github-actions · 2024-08-08T09:46:34Z

Flaky tests detected in cb6485c.
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/10299502863
📝 Reported issues:

[Flaky Test] Redirection after template creation #60678 in /test/e2e/specs/site-editor/site-editor-url-navigation.spec.js

ciampo self-assigned this Jul 18, 2024

ciampo added the [Type] Developer Documentation Documentation for developers label Jul 18, 2024

ciampo requested a review from a team July 18, 2024 15:30

ciampo marked this pull request as ready for review July 18, 2024 15:31

ciampo requested a review from ajitbohra as a code owner July 18, 2024 15:31

ciampo changed the title ~~Components: update contributing guidelines and add "Naming conventions" section~~ Components: add "Naming conventions" section Jul 18, 2024

ciampo commented Jul 18, 2024

View reviewed changes

packages/components/CONTRIBUTING.md Outdated Show resolved Hide resolved

tyxla reviewed Jul 19, 2024

View reviewed changes

packages/components/CONTRIBUTING.md Show resolved Hide resolved

packages/components/CONTRIBUTING.md Outdated Show resolved Hide resolved

packages/components/CONTRIBUTING.md Outdated Show resolved Hide resolved

packages/components/CONTRIBUTING.md Outdated Show resolved Hide resolved

mirka reviewed Jul 19, 2024

View reviewed changes

packages/components/CONTRIBUTING.md Show resolved Hide resolved

mirka mentioned this pull request Jul 20, 2024

Composite: stabilize new ariakit implementation #63564

Merged

DaniGuardiola reviewed Jul 24, 2024

View reviewed changes

ciampo mentioned this pull request Jul 30, 2024

@wordpress/components: agree on a naming convention for compound (sub) components #63242

Closed

ciampo force-pushed the docs/components-contributing-guidelines-compound-naming branch from b26f91e to bdfe95c Compare July 31, 2024 15:05

ciampo requested review from mirka, tyxla and DaniGuardiola July 31, 2024 15:33

tyxla reviewed Aug 1, 2024

View reviewed changes

mirka reviewed Aug 2, 2024

View reviewed changes

diegohaz reviewed Aug 3, 2024

View reviewed changes

packages/components/CONTRIBUTING.md Outdated Show resolved Hide resolved

ciampo added 5 commits August 8, 2024 09:10

Use update compound suggested notation

6e01a82

Remove reference to item group as it may not reflect anymore all rece…

a60e160

…nt best practices

Tweak part about experimental APIs

ded6733

Fix spacing

d5d68b0

Linter auto-formatting

93d2e7a

ciampo added 7 commits August 8, 2024 09:10

Add Naming Conventions section

75146a4

Update guidelines to use overloaded convention, remove references to …

9d3fc3c

…monolithic components

Added more details to the JSX example

887ab11

Grammar

d28325b

Split unforwarded component from forwardRef call

c7f37d1

Fix comment + auto-format

790fd15

Add section on JSDocs + IntelliSense requirements + recommended best …

432635b

…practices

ciampo force-pushed the docs/components-contributing-guidelines-compound-naming branch from 737dbb6 to 432635b Compare August 8, 2024 07:34

ciampo requested review from mirka and tyxla August 8, 2024 07:37

tyxla approved these changes Aug 8, 2024

View reviewed changes

packages/components/CONTRIBUTING.md Outdated Show resolved Hide resolved

Use named functions without attributing them to const

cb6485c

ciampo enabled auto-merge (squash) August 8, 2024 09:31

ciampo merged commit 236250e into trunk Aug 8, 2024
60 of 61 checks passed

ciampo deleted the docs/components-contributing-guidelines-compound-naming branch August 8, 2024 09:59

github-actions bot added this to the Gutenberg 19.1 milestone Aug 8, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Components: add "Naming conventions" section #63714

Components: add "Naming conventions" section #63714

ciampo commented Jul 18, 2024 •

edited

Loading

ciampo commented Jul 18, 2024

github-actions bot commented Jul 18, 2024 •

edited

Loading

ciampo Jul 18, 2024

tyxla Aug 1, 2024

ciampo Jul 18, 2024

tyxla left a comment

DaniGuardiola left a comment

mirka commented Jul 30, 2024 •

edited

Loading

ciampo commented Jul 31, 2024

tyxla left a comment

tyxla Aug 1, 2024

mirka Aug 2, 2024

ciampo Aug 8, 2024 •

edited

Loading

tyxla Aug 1, 2024

mirka left a comment

ciampo commented Aug 8, 2024

tyxla left a comment

github-actions bot commented Aug 8, 2024

Components: add "Naming conventions" section #63714

Components: add "Naming conventions" section #63714

Conversation

ciampo commented Jul 18, 2024 • edited Loading

What?

Why?

ciampo commented Jul 18, 2024

github-actions bot commented Jul 18, 2024 • edited Loading

ciampo Jul 18, 2024

Choose a reason for hiding this comment

tyxla Aug 1, 2024

Choose a reason for hiding this comment

ciampo Jul 18, 2024

Choose a reason for hiding this comment

tyxla left a comment

Choose a reason for hiding this comment

DaniGuardiola left a comment

Choose a reason for hiding this comment

mirka commented Jul 30, 2024 • edited Loading

ciampo commented Jul 31, 2024

tyxla left a comment

Choose a reason for hiding this comment

tyxla Aug 1, 2024

Choose a reason for hiding this comment

mirka Aug 2, 2024

Choose a reason for hiding this comment

ciampo Aug 8, 2024 • edited Loading

Choose a reason for hiding this comment

tyxla Aug 1, 2024

Choose a reason for hiding this comment

mirka left a comment

Choose a reason for hiding this comment

ciampo commented Aug 8, 2024

tyxla left a comment

Choose a reason for hiding this comment

github-actions bot commented Aug 8, 2024

ciampo commented Jul 18, 2024 •

edited

Loading

github-actions bot commented Jul 18, 2024 •

edited

Loading

mirka commented Jul 30, 2024 •

edited

Loading

ciampo Aug 8, 2024 •

edited

Loading