Skip to content

Commit 4e37375

Browse files
dndungudndungu
committed
docs(adr): add API stability contract for v1.0.0
1 parent 5387ee0 commit 4e37375

1 file changed

Lines changed: 141 additions & 0 deletions

File tree

‎docs/adr/002-api-stability-v1.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# ADR 002: API Stability Contract for v1.0.0
2+
3+
## Status
4+
Accepted
5+
6+
## Date
7+
2026-03-29
8+
9+
## Context
10+
zonnx is approaching v1.0.0. Consumers need to know which exported types and functions are covered by semantic versioning guarantees and which may change in minor releases. This ADR documents the stability contract so that importers can depend on zonnx with confidence and maintainers know what constitutes a breaking change.
11+
12+
## Decision
13+
14+
### Stability Tiers
15+
16+
**Stable** -- covered by Go module semantic versioning from v1.0.0 onward. Removing, renaming, or changing the signature of these symbols requires a major version bump.
17+
18+
**Extensible** -- new fields, methods, or enum values may be added in minor releases. Callers should not rely on exhaustive switches or struct literal initialization without field names.
19+
20+
**Internal** -- not part of the public API. May change or be removed in any release.
21+
22+
### Package-by-Package Guarantees
23+
24+
#### `safetensors` (Stable)
25+
26+
| Symbol | Kind | Stability | Notes |
27+
|--------|------|-----------|-------|
28+
| `Open(path string) (*File, error)` | func | Stable | |
29+
| `File` | struct | Stable | Opaque; interact via methods only |
30+
| `File.Close() error` | method | Stable | |
31+
| `File.TensorNames() []string` | method | Stable | |
32+
| `File.TensorInfo(name string) (TensorInfo, bool)` | method | Stable | |
33+
| `File.ReadTensor(name string) ([]byte, error)` | method | Stable | |
34+
| `File.ReadFloat32(name string) ([]float32, error)` | method | Stable | New dtype support may be added |
35+
| `TensorInfo` | struct | Extensible | New fields may be added; use named fields in literals |
36+
37+
#### `pkg/downloader` (Stable)
38+
39+
| Symbol | Kind | Stability | Notes |
40+
|--------|------|-----------|-------|
41+
| `ModelSource` | interface | Stable | Will not add methods; safe to implement externally |
42+
| `ModelSource.DownloadModel(...)` | method | Stable | |
43+
| `Downloader` | struct | Stable | Opaque |
44+
| `NewDownloader(source ModelSource) *Downloader` | func | Stable | |
45+
| `Downloader.Download(...)` | method | Stable | |
46+
| `DownloadResult` | struct | Extensible | New fields may be added |
47+
| `HuggingFaceSource` | struct | Stable | Opaque |
48+
| `NewHuggingFaceSource(apiKey string) *HuggingFaceSource` | func | Stable | |
49+
| `HuggingFaceSource.DownloadModel(...)` | method | Stable | |
50+
| `HuggingFaceModelInfo` | struct | Extensible | Mirrors upstream API; fields may be added |
51+
52+
#### `pkg/gguf` (Stable)
53+
54+
| Symbol | Kind | Stability | Notes |
55+
|--------|------|-----------|-------|
56+
| `MapTensorName(name string) string` | func | Stable | New mappings may be added |
57+
| `MapMetadata(arch string, config map[string]interface{}) []MetadataEntry` | func | Stable | New metadata keys may be emitted |
58+
| `MetadataEntry` | struct | Extensible | New fields may be added |
59+
60+
#### `pkg/converter` (Stable)
61+
62+
| Symbol | Kind | Stability | Notes |
63+
|--------|------|-----------|-------|
64+
| `ConvertSafetensorsToGGUF(inputDir, outputPath, arch string) error` | func | Stable | |
65+
| `ONNXToZMF(model *onnx.ModelProto) (*zmf.Model, error)` | func | Stable | |
66+
| `ONNXToZMFWithPath(model *onnx.ModelProto, modelPath string) (*zmf.Model, error)` | func | Stable | |
67+
68+
#### `pkg/importer` (Stable)
69+
70+
| Symbol | Kind | Stability | Notes |
71+
|--------|------|-----------|-------|
72+
| `LoadOnnxModel(path string) (*onnx.ModelProto, error)` | func | Stable | |
73+
| `ConvertOnnxToZmf(path string) (*zmf.Model, error)` | func | Stable | |
74+
75+
#### `pkg/inspector` (Stable)
76+
77+
| Symbol | Kind | Stability | Notes |
78+
|--------|------|-----------|-------|
79+
| `InspectONNX(inputFile string) error` | func | Stable | Output format may change |
80+
| `InspectZMF(inputFile string) error` | func | Stable | Output format may change |
81+
82+
#### `pkg/quantize` (Stable)
83+
84+
| Symbol | Kind | Stability | Notes |
85+
|--------|------|-----------|-------|
86+
| `QuantType` | type | Extensible | New values (e.g. Q5_1) may be added |
87+
| `Q4_0`, `Q8_0` | const | Stable | |
88+
| `Model(m *zmf.Model, qt QuantType) error` | func | Stable | |
89+
90+
#### `pkg/registry` (Stable)
91+
92+
| Symbol | Kind | Stability | Notes |
93+
|--------|------|-----------|-------|
94+
| `Register(opType string, constructor LayerConstructor)` | func | Stable | |
95+
| `Get(opType string) (LayerConstructor, bool)` | func | Stable | |
96+
| `LayerConstructor` | type | Stable | Signature will not change |
97+
| `ConversionContext` | struct | Extensible | New fields may be added for richer conversion |
98+
99+
#### `pkg/zmf_inspector` (Stable)
100+
101+
| Symbol | Kind | Stability | Notes |
102+
|--------|------|-----------|-------|
103+
| `Load(file string) (*zmf.Model, error)` | func | Stable | |
104+
| `Inspect(model *zmf.Model)` | func | Stable | Output format may change |
105+
106+
#### `internal/onnx` (Internal)
107+
108+
Generated protobuf code. Not part of the public API. May be regenerated or restructured in any release.
109+
110+
#### `cmd/zonnx`, `cmd/granite2gguf` (Internal)
111+
112+
CLI entry points. Command-line flags and output format are not covered by the stability contract.
113+
114+
### Safe Extensions (no major version bump required)
115+
116+
The following changes are permitted in minor releases:
117+
118+
- Adding new exported functions, methods, or types to any package.
119+
- Adding new fields to Extensible structs.
120+
- Adding new `QuantType` constants.
121+
- Adding new ONNX op support in `pkg/registry` and `pkg/importer/layers/`.
122+
- Adding new tensor name or metadata mappings in `pkg/gguf`.
123+
- Changing human-readable output format of inspector functions.
124+
125+
### Breaking Changes (require major version bump)
126+
127+
- Removing or renaming any Stable symbol.
128+
- Changing the signature of any Stable function or method.
129+
- Adding methods to the `ModelSource` interface.
130+
- Changing the semantics of an existing function in a way that breaks existing callers.
131+
132+
## Consequences
133+
134+
**Positive:**
135+
- Importers can depend on zonnx v1.x with clear expectations about what will and will not change.
136+
- The Extensible tier gives maintainers room to evolve structs without a major version bump.
137+
- The `ModelSource` interface is explicitly frozen, so third-party implementations are safe.
138+
139+
**Negative:**
140+
- Freezing the `ModelSource` interface means new capabilities must be added via new interfaces or wrapper types rather than extending the existing one.
141+
- CLI output is excluded from stability guarantees, which may surprise users who script against it.

0 commit comments

Comments
 (0)