Feature/uuidv8

[cameracker]

This PR adds v8 support to the package.

This variant is for "custom" implementations where there is very little standardized other than the the bit arrangement of the UUID. Version and Variant bits are set same as other UUID formats.

We will need to release this as a major version update because it adds a function to the Generator interface.

EDIT: Reviewing a previous decision about adding vNAtTime() to the Generator interface without incrementing a major version, I'd be comfortable with going the same route. Open to feedback.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (master@74d7e0c). Learn more about missing BASE report.
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##             master      #241   +/-   ##
==========================================
  Coverage          ?   100.00%           
==========================================
  Files             ?         5           
  Lines             ?       457           
  Branches          ?         0           
==========================================
  Hits              ?       457           
  Misses            ?         0           
  Partials          ?         0           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR adds UUIDv8 support (RFC 9562) to the library, enabling callers to construct version 8 UUIDs from custom user-provided fields.

Changes:

• Introduces the V8 UUID version constant and documents v8 as supported.
• Adds NewV8 at both package level and generator level, including validation and a new sentinel error (ErrV8FieldLength).
• Adds generator tests covering UUIDv8 creation, field placement, version/variant bits, and invalid input lengths.

Reviewed changes

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

Show a summary per file

File	Description
uuid.go	Exposes V8 as an official UUID version constant.
generator.go	Adds UUIDv8 generation API and implementation, plus a new method on the Generator interface.
error.go	Adds ErrV8FieldLength sentinel error for invalid UUIDv8 field lengths.
generator_test.go	Adds test coverage for UUIDv8 creation, bit layout, and validation errors.
README.md	Lists Version 8 as a supported UUID version.

---

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

[Copilot]

@cameracker I've opened a new pull request, #244, to work on those changes. Once the pull request is ready, I'll request review from you.

[kohenkatz]

LGTM

[cameracker]

@dylan-bourque @kohenkatz do you guys have a preference on how this is released (major or minor)? Technically this changes the generator interface in a "breaking" way but I really doubt that many people are using the generator interface...

[dylan-bourque]

@dylan-bourque @kohenkatz do you guys have a preference on how this is released (major or minor)? Technically this changes the generator interface in a "breaking" way but I really doubt that many people are using the generator interface...

👎 on a major version for this IMO. Adding a new method shouldn't require every consumer out there to have to update every reference to our library. The non-breaking option would be define a new GeneratorV8 interface that embeds Generator and adds the new method, but I like that even less.

If we do release as v5.x then we should be sure to include a loud callout in the release notes that the Generator interface has changed.

[dylan-bourque]

A consideration: #246 could also pedantically be considered a breaking change (since existing consumers using Go < 1.25 will stop working). I would argue against a major version for that change as well, but maybe it's worth it if we have more than one breakage. 🤔

[cameracker]

A consideration: #246 could also pedantically be considered a breaking change (since existing consumers using Go < 1.25 will stop working). I would argue against a major version for that change as well, but maybe it's worth it if we have more than one breakage. 🤔

I'll put up an issue and ask for community feedback for a couple of weeks and then kick it out as a minor if we dont hear anything

[cameracker]

Alight I'm gonna merge this thing in next but git decided the readme had a conflict for some reason.... Needs a reapproval