A Zig library for generating, parsing, and formatting RFC 9562 UUIDs.
zig-uuid CONTRIBUTING.md
3.3 kB · 99 lines
Markdown
at main

Contributing to zig-uuid #

Thank you for wanting to help. This file covers what you need to know to make a change and get it accepted. README.md says what zig-uuid is and how it is used.

Where to send changes #

Report issues and send pull requests to the Tangled mirror: https://tangled.org/jcollie.dev/zig-uuid.

Setting up #

Everything is pinned in the Nix flake, Zig 0.17.0 included:

$ git clone https://git.jcollie.dev/jeff/zig-uuid.git
$ cd zig-uuid
$ nix develop

The development shell has zig, reuse and git-pages-cli. Without Nix, you need Zig 0.17.0 and nothing else: the library has no dependencies.

The zig-0.16 branch holds the version that builds with Zig 0.16. Only critical fixes are backported to it; everything else goes to main.

Before you send a change #

CI runs these, and a change has to pass all of them:

$ reuse lint                            # every file has a license
$ zig fmt --check --exclude zig-pkg .   # Zig is formatted
$ zig build test --summary all          # the tests
$ zig build                             # the example program

zig build docs should also succeed, since the documentation is published from main once the tests pass.

Where things are #

Path What
src/uuid.zig The whole library: the UUID type, creation, parsing and formatting, and the tests
src/main.zig A small program that prints a random UUID, run with zig build run
src/bench.zig Benchmarks of parsing and formatting, run with zig build bench

Making changes #

Tests #

Every behavior change comes with a test, at the bottom of src/uuid.zig. Where RFC 9562 gives an example value or a test vector, test against it and link the section of the RFC in a comment beside the test.

Errors #

Malformed input is an error, never a panic. Parsing returns error.MalformedUUID for anything that is not one of the accepted forms.

Design #

The library makes no allocations and reads nothing from the environment implicitly: timestamps, randomness and node IDs come from the caller through UUID.NewOptions. A change that adds a dependency, an allocation or a hidden source of time or randomness will not be accepted. UUID stays a packed union of exactly 128 bits.

Performance #

Parsing and formatting are on the hot path for many callers. If a change touches them, run zig build bench before and after and say what changed.

Documentation #

The API documentation is generated from doc comments and published at https://jeff.jcollie.page/zig-uuid/. A public declaration gets a doc comment, with a link to the part of RFC 9562 it implements where there is one. When behavior changes, update README.md to describe how things are now, not how they changed.

Licensing #

zig-uuid is MIT licensed and follows REUSE. Every new file starts with an SPDX header like the ones already in the tree; a file that cannot hold one goes in REUSE.toml. By sending a change you agree to license it under the MIT license.

Commits #

The first line is a short summary in the imperative ("add the Windows registry form"). The body explains what changed and why.