Skip to content

docs: add v7 migration guide (v6 → v7) - #1396

Open
tusharpandey13 wants to merge 1 commit into
masterfrom
docs/v7-migration-guide
Open

docs: add v7 migration guide (v6 → v7)#1396
tusharpandey13 wants to merge 1 commit into
masterfrom
docs/v7-migration-guide

Conversation

@tusharpandey13

Copy link
Copy Markdown
Contributor

Summary

Adds v7_MIGRATION_GUIDE.md, the release-level upgrade guide for 6.x7.x, following the conventions of the existing v5/v6 guides. Kept separate from the Authentication API deep-dive guide (#1395), which it references rather than duplicates.

v7 makes node-auth0 a Management-API-only SDK. This guide is the umbrella that covers the full breaking surface of that release:

  • Authentication API removed from the main entrypoint — points to AUTH_MIGRATION_GUIDE.md for the method-by-method rewrite.
  • Removed-exports tableAuthenticationClient, UserInfoClient, AuthApiError, AuthenticationClientOptions, IDTokenValidateOptions, IdTokenValidatorError, TokenSet, SUBJECT_TOKEN_TYPES, UserInfoResponse, UserInfoError, each mapped to its v7 replacement.
  • Management-side breaking changes not in scope of the auth guide: mTLS requires an explicit fetch; mTLS + client-assertion mutually exclusive; bare-hostname domain validation; token-acquisition failures throw ManagementError; uuid dependency removed.
  • Legacy entrypoint documented as a stopgap.

Also links the new guide from the README documentation list.

Why a separate guide (not a rename of AUTH_MIGRATION_GUIDE)

AUTH_MIGRATION_GUIDE.md (#1395) is a topic guide for the auth-layer rewrite and explicitly scopes out the Management API. v7 is a superset: it also covers the Management-side breaks and the export-surface removals, matching how the v6 guide is the release umbrella. Renaming the auth guide would silently drop two-thirds of the v7 breaking surface.

Base branch

Targets feat/auth-separation-v6 (the v7 [BREAKING] release branch, #1390) so the guide ships with the release it documents.

Related PRs

🤖 Generated with Claude Code

@tusharpandey13
tusharpandey13 requested a review from a team as a code owner August 27, 2026 08:22
@tusharpandey13
tusharpandey13 changed the base branch from feat/auth-separation-v6 to master August 27, 2026 11:19
Add v7_MIGRATION_GUIDE.md covering the 6.x to 7.x upgrade: Authentication
API removed from the main entrypoint, the removed-exports table, and the
Management-side breaking changes (mTLS explicit fetch, mTLS/client-assertion
mutual exclusion, bare-hostname domain validation, ManagementError on token
acquisition failures, uuid dependency removed).

Delegates the auth-layer rewrite detail to AUTH_MIGRATION_GUIDE.md rather
than duplicating it, and links the legacy entrypoint as a stopgap.

Link the new guide from the README documentation list.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@tusharpandey13
tusharpandey13 force-pushed the docs/v7-migration-guide branch from 6a628b2 to dd07f02 Compare August 27, 2026 12:18
@codecov

codecov Bot commented Aug 27, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.73%. Comparing base (f9d6413) to head (dd07f02).

Additional details and impacted files

Impacted file tree graph

@@           Coverage Diff            @@
##           master    #1396    +/-   ##
========================================
  Coverage   89.73%   89.73%            
========================================
  Files         441      441            
  Lines       20799    20799            
  Branches    10146     9809   -337     
========================================
  Hits        18663    18663            
  Misses       2136     2136            
Flag Coverage Δ
alltests 89.73% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant