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.

generated by opus.

[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.

[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 e5476cf:

✅ 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.

[sdwheeler]

@SufficientDaikon PS 7.7 has released. Please rebase and retarget your changes to the 7.7 version of the content.

[SufficientDaikon]

@SufficientDaikon PS 7.7 has released. Please rebase and retarget your changes to the 7.7 version of the content.

Thanks for the heads up, ill get on it assap

[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.

[Copilot]

Pull request overview

Documents a breaking change to New-Guid default UUID generation (v4 → v7) and adds corresponding release-note entries so users understand the behavioral difference and how to produce v4/v7 explicitly.

Changes:

• Updates New-Guid cmdlet reference content to describe UUID v7 as the default and adds a .NET API example (CreateVersion7() vs NewGuid()).
• Adds New-Guid UUID v7 default-change entries to the PowerShell release notes (breaking changes + cmdlet improvements).
• Adds a new release-note reference link for the associated engine PR.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-76.md	Adds release-note bullets describing the New-Guid default UUID v7 change and links to the engine PR.
reference/7.6/Microsoft.PowerShell.Utility/New-Guid.md	Updates cmdlet reference description/notes and adds an example showing explicit v4/v7 UUID creation via .NET APIs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[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 3911611:

✅ 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.

[learn-build-service-prod]

Learn Build status updates of commit 5f757e9:

✅ Validation status: passed

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

For more details, please refer to the build report.

[SufficientDaikon]

@sdwheeler anything else?

also, why did copilot trigger? it says it started a review on my behalf?? since when?? xD it also gives a 404 when i click review session??