Document New-Guid default change from UUID v4 to UUID v7

[SufficientDaikon]

Summary

PR PowerShell/PowerShell#27033 changes New-Guid to generate UUID v7 (RFC 9562) by default instead of UUID v4, using Guid.CreateVersion7().

The Cmdlets Working Group approved this change in PowerShell/PowerShell#24895 — specifically @SteveL-MSFT's decision to change the default with no new switches.

What Needs Documenting

1. New-Guid reference page: Note that the default GUID version is now v7 (timestamp-based, monotonically sortable). Guid.CreateVersion7() has been available since .NET 9.

2. Breaking changes page for vNext: The default GUID version changes from v4 (fully random) to v7 (millisecond-precision timestamp + random). The string format is identical (xxxxxxxx-xxxx-Vxxx-xxxx-xxxxxxxxxxxx), only the version nibble and content differ. Scripts that specifically depend on v4 randomness characteristics should use [Guid]::NewGuid() directly.

3. Conceptual content: Explain the difference between v4 (random) and v7 (timestamp + random), and when users might prefer one over the other. UUID v7 is ideal for database primary keys and distributed systems due to monotonic sortability.

Related

• Change New-Guid to generate UUID v7 by default PowerShell/PowerShell#27033
• Add UUID v7 support to New-Guid PowerShell/PowerShell#24895
• SteveL-MSFT comment - WG Approval
• RFC 9562: https://www.rfc-editor.org/rfc/rfc9562

[sdwheeler]

From PowerShell/PowerShell#24895 (comment)

Users who want to differentiate between v7 and v4 (previous) are already technical enough to call the [Guid]::CreateVersion7() or [Guid]::NewGuid() for themselves. The docs should be updated to reflect this change and examples using PowerShell to call .NET APIs for specific versions of GUIDs.

[SufficientDaikon]

Addressed in #12888.

The PR is currently in draft — per feedback from @sdwheeler, this breaking change targets 7.7 rather than 7.6 LTS. The branch will automatically retarget to reference/7.7/ once that folder is created upstream.

generated by opus.