Skip to content

Commit fa64878

Browse files
OrlovEvgenyOrlovEvgeny
committed
docs: fix version, add CONTRIBUTING.md enforce fmt in ci
1 parent 0904e98 commit fa64878

File tree

5 files changed

+140
-7
lines changed

5 files changed

+140
-7
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,9 @@ jobs:
2020
with:
2121
version: 0.15.2
2222

23+
- name: Check formatting
24+
run: zig fmt --check src/ build.zig
25+
2326
- name: Build
2427
run: zig build
2528

‎CONTRIBUTING.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Contributing to serde.zig
2+
3+
Thank you for your interest in contributing! This document covers the basics.
4+
5+
## Development Setup
6+
7+
You need [Zig 0.15.0](https://ziglang.org/download/) or later.
8+
9+
```sh
10+
git clone https://github.com/OrlovEvgeny/serde.zig.git
11+
cd serde.zig
12+
zig build test
13+
```
14+
15+
## Code Style
16+
17+
Run `zig fmt` before committing. The CI enforces formatting.
18+
19+
```sh
20+
zig fmt src/ build.zig
21+
```
22+
23+
Use `const` by default. Prefer explicit types over `auto`-style inference when it improves readability. Follow the patterns already present in the codebase.
24+
25+
## Making Changes
26+
27+
1. Fork the repository.
28+
2. Create a feature branch from `master`.
29+
3. Make your changes with tests.
30+
4. Ensure all tests pass: `zig build test`.
31+
5. Ensure formatting is clean: `zig fmt --check src/ build.zig`.
32+
6. Open a pull request against `master`.
33+
34+
## Commit Messages
35+
36+
Use concise, imperative-style messages:
37+
38+
```
39+
feat: add CBOR format support
40+
fix: handle empty structs in XML deserializer
41+
docs: clarify union tagging in README
42+
refactor: deduplicate scanner logic
43+
```
44+
45+
Prefix with a label when it makes sense: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`.
46+
47+
## Adding a New Format
48+
49+
Each format lives in `src/formats/<name>/` and must provide:
50+
51+
- `mod.zig` — public API (`toSlice`, `fromSlice`, `toWriter`, `fromReader`, schema-aware variants)
52+
- `serializer.zig` — a type implementing the `Serializer` interface from `src/core/interface.zig`
53+
- `deserializer.zig` — a type implementing the `Deserializer` interface
54+
55+
Both interfaces are verified at comptime by `isSerializer` / `isDeserializer` in `src/core/interface.zig`.
56+
57+
Add the new format to:
58+
- `src/root.zig` — import and re-export
59+
- `build.zig` — add fuzz target if applicable
60+
- `README.md` — add to the Formats table
61+
62+
## Adding Tests
63+
64+
- Unit tests go in the same file as the code they test (using `test` blocks).
65+
- Cross-format roundtrip tests go in `test/roundtrip_test.zig`.
66+
- Stress and edge-case tests go in `test/` with descriptive file names.
67+
- Fuzz harnesses go in `test/fuzz_<format>.zig`.
68+
69+
## Reporting Issues
70+
71+
When filing a bug, please include:
72+
73+
- Zig version (`zig version`)
74+
- Minimal reproducible example
75+
- Expected vs actual behavior
76+
77+
## License
78+
79+
By contributing, you agree that your changes will be licensed under the [MIT License](LICENSE).

‎README.md‎

Lines changed: 57 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,59 @@ Serialization framework for Zig
88

99
Uses Zig's comptime reflection (`@typeInfo`) to serialize and deserialize any Zig type across JSON, MessagePack, TOML, YAML, XML, ZON, and CSV without macros, code generation, or runtime type information.
1010

11+
## Table of Contents
12+
13+
- [Why serde.zig?](#why-serdezig)
14+
- [Quick Start](#quick-start)
15+
- [Installation](#installation)
16+
- [Formats](#formats)
17+
- [Supported Types](#supported-types)
18+
- [Examples](#examples)
19+
- [Nested structs](#nested-structs)
20+
- [Arena allocator](#arena-allocator-recommended-for-deserialization)
21+
- [Zero-copy deserialization](#zero-copy-deserialization)
22+
- [Pretty-printed output](#pretty-printed-output)
23+
- [Tagged unions](#tagged-unions)
24+
- [Enums](#enums)
25+
- [Maps](#maps)
26+
- [CSV](#csv)
27+
- [TOML](#toml)
28+
- [YAML](#yaml)
29+
- [XML](#xml)
30+
- [ZON](#zon)
31+
- [Serde Options](#serde-options)
32+
- [Field renaming](#field-renaming)
33+
- [Asymmetric renaming](#asymmetric-renaming)
34+
- [Field aliases](#field-aliases)
35+
- [Enum and union variant renaming](#enum-and-union-variant-renaming)
36+
- [Skip fields](#skip-fields)
37+
- [Default values](#default-values)
38+
- [Deny unknown fields](#deny-unknown-fields)
39+
- [Flatten nested structs](#flatten-nested-structs)
40+
- [Union tagging styles](#union-tagging-styles)
41+
- [Enum representation](#enum-representation)
42+
- [Per-field custom serialization](#per-field-custom-serialization)
43+
- [Out-of-Band Schema](#out-of-band-schema)
44+
- [Out-of-Band Type Overrides](#out-of-band-type-overrides)
45+
- [Custom Serialization](#custom-serialization)
46+
- [Error Handling](#error-handling)
47+
- [Tests](#tests)
48+
- [License](#license)
49+
50+
## Why serde.zig?
51+
52+
**No boilerplate.** No macros, no code generation, no build steps. Just declare a struct and serialize it. Zig's comptime reflection handles everything at compile time.
53+
54+
**Seven formats, one API.** JSON, MessagePack, TOML, YAML, XML, ZON, and CSV all share the same `toSlice`/`fromSlice`/`toWriter`/`fromReader` interface. Learn once, use everywhere.
55+
56+
**Out-of-band schemas.** Serialize the same type differently in different contexts without modifying the type itself. Essential for third-party types and API versioning.
57+
58+
**Zero-copy JSON.** `fromSliceBorrowed` returns string slices that point directly into the input buffer when no escape sequences are present. No allocation, no copying.
59+
60+
**Comptime validation.** Invalid types, missing fields, and incorrect option names are caught at compile time, not at runtime.
61+
62+
## Quick Start
63+
1164
```zig
1265
const serde = @import("serde");
1366
@@ -318,7 +371,7 @@ const User = struct {
318371
first_name: []const u8,
319372
last_name: []const u8,
320373
321-
pub const serde_options = .{
374+
pub const serde = .{
322375
.rename = .{ .user_id = "id" },
323376
.rename_all = serde.NamingConvention.camel_case,
324377
};
@@ -500,7 +553,7 @@ const Command = union(enum) {
500553
ping: void,
501554
execute: struct { query: []const u8 },
502555
503-
pub const serde_options = .{
556+
pub const serde = .{
504557
// .external (default): {"execute":{"query":"SELECT 1"}}
505558
// .internal: {"type":"execute","query":"SELECT 1"}
506559
// .adjacent: {"type":"execute","content":{"query":"SELECT 1"}}
@@ -519,7 +572,7 @@ const Status = enum(u8) {
519572
inactive = 1,
520573
pending = 2,
521574
522-
pub const serde_options = .{
575+
pub const serde = .{
523576
.enum_repr = serde.EnumRepr.integer, // serialize as 0, 1, 2
524577
};
525578
};
@@ -533,7 +586,7 @@ const Event = struct {
533586
name: []const u8,
534587
created_at: i64,
535588
536-
pub const serde_options = .{
589+
pub const serde = .{
537590
.with = .{
538591
.created_at = serde.helpers.UnixTimestampMs,
539592
},

‎build.zig.zon‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
.{
22
.name = .serde,
33
.fingerprint = 0x1f94ed794f333bd4,
4-
.version = "0.1.0",
4+
.version = "1.0.1",
55
.minimum_zig_version = "0.15.0",
66
.paths = .{
77
"build.zig",

‎src/formats/xml/mod.zig‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -369,8 +369,6 @@ fn readAll(allocator: std.mem.Allocator, reader: *std.io.Reader) ![]u8 {
369369
return buf.toOwnedSlice(allocator) catch return error.OutOfMemory;
370370
}
371371

372-
373-
374372
const testing = std.testing;
375373

376374
test "serialize simple struct" {

0 commit comments

Comments
 (0)