Skip to content

New API version release#3380

Open
brunol95 wants to merge 10 commits into
mainfrom
bruno/user-5311-latest-api-version
Open

New API version release#3380
brunol95 wants to merge 10 commits into
mainfrom
bruno/user-5311-latest-api-version

Conversation

@brunol95
Copy link
Copy Markdown
Contributor

@brunol95 brunol95 commented May 18, 2026 •
edited by manovotny
Loading

🔎 Previews:

What does this solve? What changed?

In the next API version, metadata updates through the user update method are disallowed. This PR documents the API version page along with sdk changes to support the new version.

Todos

Deadline

  • 05/26

@brunol95 brunol95 requested a review from a team as a code owner May 18, 2026 20:38
@vercel
Copy link
Copy Markdown

vercel Bot commented May 18, 2026 •
edited
Loading

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
clerk-docs Ready Ready Preview May 26, 2026 10:11pm

Request Review

@brunol95 brunol95 marked this pull request as draft May 18, 2026 20:38
@brunol95 brunol95 marked this pull request as ready for review May 20, 2026 17:46
@manovotny manovotny self-assigned this May 22, 2026
@manovotny @claude
docs: Fix metadata example diff highlighting, NOTE callouts, and para…
3414da8 
…m type name

- Correct del/ins line ranges in the 2026-05-12 and Core 3 metadata
  examples so closing braces highlight correctly
- Use > [!NOTE] callouts on the native mobile user pages
- Align updateUserMetadata() param type with @clerk/backend (UserMetadataParams)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@manovotny
Copy link
Copy Markdown
Contributor

manovotny commented May 22, 2026

Pushed some review fixes directly in 3414da8.

  • Fixed the del/ins line ranges in the metadata examples so the diff highlighting is correct: the backend example in the 2026-05-12 guide now highlights replaceUserMetadata()'s closing line, and the frontend user.update() examples (in both the 2026-05-12 guide and the Core 3 accordion) now account for the 6-line block instead of treating it as 5.
  • Switched the native iOS/Android > Note: blockquotes to > [!NOTE] callouts to match the other native-mobile pages.
  • Renamed the updateUserMetadata() params type from UpdateUserMetadataParams to UserMetadataParams so it matches @clerk/backend and the new replaceUserMetadata() page.

Have a look, and let me know if anything looks off. I also updated the todo list in the PR description with a few more items.

manovotny
manovotny reviewed May 22, 2026
View reviewed changes
Comment thread docs/guides/development/upgrading/versioning.mdx
| Python | TBD |
| Remix | TBD |
| Ruby | TBD |
| Vue | TBD |
Copy link
Copy Markdown
Contributor

@manovotny manovotny May 22, 2026

Choose a reason for hiding this comment

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

Leaving a comment to flag that TBDs need to be fixed before merge. From @brunol95:

On the day of the release - my plan is to update the docs with all the latest version once the sdk PRs are merged/released

@SarahSoutoul SarahSoutoul self-assigned this May 22, 2026
@SarahSoutoul
Copy link
Copy Markdown
Contributor

SarahSoutoul commented May 26, 2026

@brunol95 left a docs review with some small fixes:

  • Made consistent the phrase future major API version across the changes as some were using future major version
  • Made consistent all of the deprecated properties changes to be consistent with rest of docs.
  • Improved the wording of some of the text.

I noticed there was still a mention of client.users.updateUser() but from my understanding, it's fine to keep it as is cause we're not updating any publicMetadata or the other metadata properties. Is that correct?

Screenshot 2026-05-26 at 12 00 17 pm

SarahSoutoul
SarahSoutoul reviewed May 26, 2026
View reviewed changes
Comment thread docs/reference/native-mobile/user.mdx Outdated
@manovotny @claude
docs: Clarify metadata deprecation paths and reposition native callouts
0886311 
- updateUser() metadata param deprecation points to both
  updateUserMetadata() (partial/merge) and replaceUserMetadata()
  (full replacement) so migrators relying on replace semantics
  aren't silently switched to merge
- Drop "API" from "future major API version" — these are SDK
  deprecations, not bound to a future API version date
- Move the deprecation > [!NOTE] callout to the top of the
  "Update user metadata" section on the native iOS/Android pages

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@manovotny
Copy link
Copy Markdown
Contributor

manovotny commented May 26, 2026

Pushed re-review fixes directly in 0886311.

  • Expanded the deprecation guidance on updateUser()'s publicMetadata/privateMetadata/unsafeMetadata params to point to both updateUserMetadata() (partial/deep-merge) and replaceUserMetadata() (full replacement). The previous wording only mentioned the merge path, which would silently change behavior for anyone relying on updateUser()'s replace semantics.
  • Dropped "API" from "future major API version" in update-user.mdx, core-3.mdx, and objects/user.mdx. These are SDK-level deprecations — they'll be removed in a future major SDK release (per clerk/javascript#8587) — and "API version" risked conflating that with the dated API versions documented elsewhere in this PR.
  • Moved the > [!NOTE] deprecation callout to the top of the "Update user metadata" section on both user.ios.mdx and user.mdx, per Sarah's thread.

@brunol95
Copy link
Copy Markdown
Contributor Author

brunol95 commented May 27, 2026

I noticed there was still a mention of client.users.updateUser() but from my understanding, it's fine to keep it as is cause we're not updating any publicMetadata or the other metadata properties. Is that correct?

yep! client.users.updateUser() is still a valid method just can't be used for updating metadata.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@manovotny manovotny manovotny left review comments

@SarahSoutoul SarahSoutoul SarahSoutoul left review comments

At least 1 approving review is required to merge this pull request.

Assignees

@manovotny manovotny

@SarahSoutoul SarahSoutoul

Labels

do not merge

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@brunol95 @manovotny @SarahSoutoul @alexisintech