Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Popover: write better docs regarding the recent API changes #44195

Merged
merged 2 commits into from
Sep 19, 2022

Conversation

ciampo
Copy link
Contributor

@ciampo ciampo commented Sep 15, 2022

What?

Following up from #43691 (comment), this PR:

  • adds more detailed notes about recent prop deprecations while working on the Popover component
  • renames the affected CHANGELOG sections from Breaking Changes to Deprecations

@mirka I'm not sure what to do with the deprecations.md file — it looks like it hasn't been updated in some time

Dev note

Note: this dev note is a collective dev note for the recent changes to the Popover component which aimed at addressing a spike of regressions happened recently, mostly tracked in #42770

The Popover component from the @wordpress/components package has been mostly rewritten, in an effort to make it more stable, more reliable and more performant. While doing so, one of the main goals was to avoid introducing breaking changes. Here is the list with the main API changes:

  • a new placement prop has been introduced. This prop is meant to replace the legacy position prop (which will be marked as deprecated in the near future)
  • a new anchor prop has been introduced. This prop is meant to replace all previous anchor-related props (anchorRef, anchorRect, getAnchorRect). These older anchor-related props are now marked as deprecated and are scheduled to be removed in WordPress 6.3
  • the __unstableForcePosition prop has been marked as deprecated, in favour of new flip and resize props. The __unstableForcePosition is currently scheduled for removal in WordPress 6.3
  • the __unstableShift prop has been marked as deprecated, in favour of the shift prop. The __unstableShift is currently scheduled for removal in WordPress 6.3
  • the __unstableObserveElement prop has been removed, since it's not necessary anymore after the recent updates to the Popover

For more details, see the updated component's README and the Storybook examples.

The changes to the Popover component also affected the @wordpress/rich-text, where a new useAnchor hook was introduced. The previous useAnchorRef hook has been marked as deprecated, and is scheduled to be removed in WordPress 6.3.

Why?

The recent changes won't cause any breakage (apart from deprecation warnings in dev mode), and therefore should not be flagged as such.

We will flag correctly the breaking changes in future versions of Gutenberg, when we will delete those deprecated props.

How?

Editing the docs

@ciampo ciampo added [Package] Components /packages/components [Package] Rich text /packages/rich-text Needs User Documentation Needs new user documentation labels Sep 15, 2022
@ciampo ciampo self-assigned this Sep 15, 2022
@ciampo
Copy link
Contributor Author

ciampo commented Sep 15, 2022

@mirka it would be great if you could also take a look at the dev note, as part of the review 🙏

Copy link
Member

@mirka mirka left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure what to do with the deprecations.md file — it looks like it hasn't been updated in some time

Yes, I think we can leave it alone at this point 😶

component also affected the @wordpress/richt-text

Dev note looks good to me! Just one typo in the ☝️ package name here.

@@ -78,9 +79,10 @@

## 20.0.0 (2022-08-24)

### Breaking Changes
### Deprecations
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for also updating the old ones 🙏

@ciampo ciampo merged commit 56c97e8 into trunk Sep 19, 2022
@ciampo ciampo deleted the docs/popover-notes branch September 19, 2022 15:10
@github-actions github-actions bot added this to the Gutenberg 14.2 milestone Sep 19, 2022
@bph bph added the Needs Dev Note Requires a developer note for a major WordPress release cycle label Sep 21, 2022
@femkreations femkreations removed the Needs User Documentation Needs new user documentation label Jan 24, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Needs Dev Note Requires a developer note for a major WordPress release cycle [Package] Components /packages/components [Package] Rich text /packages/rich-text
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants