Document New-Guid UUID v7 default change

[SufficientDaikon]

Documents the New-Guid behavioral change from UUID v4 → v7, per the Cmdlets Working Group decision in PowerShell/PowerShell#24895.

Warning

Breaking change: New-Guid default output changes from UUID v4 (random) to UUID v7 (time-sortable). Target version updated to 7.7 per reviewer feedback — currently in draft until the reference/7.7/ folder is created upstream.

flowchart LR
    A["<b>New-Guid</b>"] -->|"7.5 and earlier"| B["UUID v4<br/><i>fully random</i>"]
    A -->|"7.7+"| C["UUID v7<br/><i>timestamp + random</i>"]
    C --> D["✓ Sortable"]
    C --> E["✓ Same string format"]
    style A fill:#4472C4,color:#fff
    style B fill:#E7E6E6,color:#333
    style C fill:#548235,color:#fff
    style D fill:#E2EFDA,color:#333
    style E fill:#E2EFDA,color:#333

Loading

What changed in the docs

File	Section	Change
New-Guid.md	DESCRIPTION	UUID v4 → v7 language, added [!NOTE] callout
New-Guid.md	Example 1	Removed word "random"
New-Guid.md	Example 5 (new)	.NET API example with CreateVersion7() / NewGuid()
New-Guid.md	NOTES	RFC 9562 reference, migration guidance
What-s-New-in-PowerShell-7x.md	Breaking changes	New entry
What-s-New-in-PowerShell-7x.md	Cmdlet improvements	New entry

Diff: DESCRIPTION before → after

- The `New-Guid` cmdlet creates a random globally unique identifier (GUID). If you need a unique
- ID in a script, you can create a GUID, as needed.
+ The `New-Guid` cmdlet creates a Version 7 globally unique identifier (GUID). Version 7 UUIDs
+ contain a millisecond-precision timestamp and are sortable. If you need a unique ID in a script,
+ you can create a GUID, as needed.
+
+ > [!NOTE]
+ > In PowerShell 7.5 and earlier, `New-Guid` created Version 4 (random) UUIDs. Starting in
+ > PowerShell 7.7, the default changed to Version 7. If you need a Version 4 UUID, use
+ > `[guid]::NewGuid()` directly.

Diff: NOTES before → after

- When used without string input or the **Empty** parameter, the cmdlet creates a Version 4
- Universally Unique Identifier (UUID). For more information, see
- [System.Guid.NewGuid](xref:System.Guid.NewGuid).
+ When used without string input or the **Empty** parameter, the cmdlet creates a Version 7
+ Universally Unique Identifier (UUID) as defined in
+ [RFC 9562](https://www.rfc-editor.org/rfc/rfc9562).
+
+ In PowerShell 7.5 and earlier, the cmdlet created a Version 4 (random) UUID. If you need a
+ Version 4 UUID, use `[guid]::NewGuid()`. To explicitly create a Version 7 UUID, use
+ `[guid]::CreateVersion7()`.
+
+ For more information, see
+ [System.Guid.CreateVersion7](xref:System.Guid.CreateVersion7).

New Example 5: .NET API usage

Per the docs team request, added an example showing .NET APIs for explicit UUID version selection with sample output highlighting the version nibble:

[guid]::CreateVersion7()   # → 019588a4-dbe2-7f30-8b9f-...  (note: 7f30)
[guid]::NewGuid()          # → d61bbeca-0186-48fa-90e1-...  (note: 48fa)

The third group reveals the version: 7xxx = v7, 4xxx = v4.

Version targeting

Important

Per @sdwheeler's feedback, this breaking change will ship in 7.7 (not 7.6 LTS). This PR is in draft until the reference/7.7/ folder is created upstream, at which point the branch will be automatically retargeted.

How the automatic retarget works

A GitHub Actions workflow on the fork runs daily:

1. Checks if reference/7.7/Microsoft.PowerShell.Utility/ exists upstream
2. When found — saves our changes, resets to upstream main, applies our diff to the 7.7 base, and force-pushes the branch
3. The reference/7.6/ files are reverted to upstream state automatically

The workflow was locally tested against the real files — diff → patch flow, Python script, and all edge cases verified under set -euo pipefail.

Scope

Updated

Only the target version reference page (New-Guid.md) and the corresponding What's New file

Unchanged

5.1 / 7.4 / 7.5 reference pages — those versions still generate UUID v4

Intentionally skipped

Pages that use New-Guid incidentally (about_Classes_Properties, about_Module_Manifests, hosting samples) — no change needed, the GUID format is identical

Related

	Link	Status
Closes	#12884
Engine PR	PowerShell/PowerShell#27033	Open
WG decision	PowerShell/PowerShell#24895 (comment)	Approved
Spec	RFC 9562	Published

PR Checklist

• Descriptive Title: This PR's title is a synopsis of the changes it proposes.
• Summary: This PR's summary describes the scope and intent of the change.
• Contributor's Guide: I have read the contributor's guide.
• Style: This PR adheres to the style guide.
• Version target: Updated to 7.7 per reviewer feedback (draft until folder exists).

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit 6421b44:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/7.6/Microsoft.PowerShell.Utility/New-Guid.md	✅Succeeded	View (powershell-7.6)
reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-76.md	✅Succeeded	View (>=powershell-5.1)

For more details, please refer to the build report.

[SufficientDaikon]

@sdwheeler — This addresses #12884 and your comment requesting .NET API examples.

What's included:

• New-Guid reference page (7.6 only) — updated DESCRIPTION, NOTES, and added Example 5 with [guid]::CreateVersion7() / [guid]::NewGuid()
• What's New in 7.6 — breaking change entry + cmdlet improvement entry

What's intentionally not included:

• 5.1 / 7.4 / 7.5 reference pages (those versions still use v4)
• Pages that use New-Guid incidentally (about_Classes_Properties, about_Module_Manifests, hosting samples) — no change needed

The engine PR (PowerShell/PowerShell#27033) is still open. This docs PR can be held until it merges.

[sdwheeler]

@SufficientDaikon Thanks for the PR. Since this is a breaking change, it won't ship in 7.6, which is an LTS release. Once it gets merged, it would ship in the next v7.7 preview release. For this command reference update, that would need to happen in the 7.7 folder, which hasn't been created yet. Once the engineering team schedules the 7.7 release I will create the 7.7 folder. The change will have to go in there.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[SufficientDaikon]

@SufficientDaikon Thanks for the PR. Since this is a breaking change, it won't ship in 7.6, which is an LTS release. Once it gets merged, it would ship in the next v7.7 preview release. For this command reference update, that would need to happen in the 7.7 folder, which hasn't been created yet. Once the engineering team schedules the 7.7 release I will create the 7.7 folder. The change will have to go in there.

okay, i understand, thanks for the comment, i'm just trying to make it easy for you to read and parse the PR and have it have everything so it's a simple merge request that doesn't break things, because some of these changes i really need in what i'm making and i've been having alot of issue with powersell

[learn-build-service-prod]

Learn Build status updates of commit f698527:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/7.6/Microsoft.PowerShell.Utility/New-Guid.md	✅Succeeded	View (powershell-7.6)
reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-76.md	✅Succeeded	View (>=powershell-5.1)

For more details, please refer to the build report.

[SufficientDaikon]

Thanks for the clarification @sdwheeler — that makes sense. I'll retarget this to reference/7.7/ once the folder is created. Converting to draft in the meantime.

I've set up a watch on the upstream repo so I can update the branch promptly when the 7.7 structure lands.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit 1f5765d:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/7.6/Microsoft.PowerShell.Utility/New-Guid.md	✅Succeeded	View (powershell-7.6)
reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-76.md	✅Succeeded	View (>=powershell-5.1)

For more details, please refer to the build report.