You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: RELEASE-MANAGEMENT.md
+2
Original file line number
Diff line number
Diff line change
@@ -7,6 +7,8 @@ Releases
7
7
8
8
Releases are versioned according to [docs/Versioning.md](docs/Versioning.md). This describes IR and operator versioning policies, as well as propose how models themselves should be versioned.
9
9
10
+
On a regular basis, new versions of ONNX are published, representing the aggregate of changes in the IR and operator sets. Such releases use semantic versioning to describe the progression of the standard.
11
+
10
12
The GitHub repo for ONNX provides release branches where the project is stabilized as per the process described here. Release notes are used to communicate the stability and status of a release. The master branch will be used to continue work for subsequent releases.
11
13
12
14
Major, minor and patch releases will have branch names and version numbers reflecting the nature of the change as per semantic versioning definitions.
Copy file name to clipboardexpand all lines: docs/IR.md
+6-6
Original file line number
Diff line number
Diff line change
@@ -41,21 +41,21 @@ Nothing in this specification should be construed as advocating one implementati
41
41
42
42
Versioning features in several places in ONNX -- the IR specification itself, the version of a model, and the version of an operator set. Futhermore, each individual operator indicates which version of its containing operator set it was introduced or stabilized in.
43
43
44
-
Version numbers can be used as a simple number, or used to encode semantic versions. If using semver, the convention is to use the two most significant bytes for the major number, the next two bytes for the minor number, and the least significant four bytes for the build/bugfix number.
44
+
Version numbers can be used as a simple number, or used to encode semantic versions. If using semver, the convention is to use the two most significant bytes for the major number, the next two bytes for the minor number, and the least significant four bytes for the build/bugfix number. When using semver versioning, at least one of the major/minor numbers MUST be non-zero.
45
45
46
-
The valid IR versions is defined by an enumeration, which currently has the following values:
46
+
The IR specification uses simple monotonically increasing numbers for its versions. The valid IR versions is defined by an enumeration, which currently has the following values:
47
47
```
48
-
// version we published on Oct 10, 2017.
48
+
// Version 1, published on Oct 10, 2017.
49
49
IR_VERSION_2017_10_10 = 0x0000000000000001;
50
50
51
-
// IR_VERSION 0.0.2 published on Oct 30, 2017
51
+
// Version 2, published on Oct 30, 2017
52
52
IR_VERSION_2017_10_30 = 0x0000000000000002;
53
53
54
-
// IR VERSION 0.0.3 published on Nov 3, 2017
54
+
// Version 3 published on Nov 3, 2017
55
55
IR_VERSION = 0x0000000000000003;
56
56
```
57
57
58
-
Operator sets use a simple number as the version number. Each operator set version represents the combination of the most recent version of each operator.
58
+
Operator sets use a simple version number. Each operator set version represents the combination of the most recent version of each operator.
59
59
60
60
This specification does not provide guidance on what versioning scheme model producers should be using.
Copy file name to clipboardexpand all lines: docs/Versioning.md
+24-20
Original file line number
Diff line number
Diff line change
@@ -11,17 +11,21 @@ ONNX defines the versioning policy and mechanism for three classes of entities:
11
11
* Operator specifications that may be referenced by a given ONNX graph. We refer to this as the *operator version*.
12
12
* A defined/trained model that defines a specific graph in terms of specific operators. We refer to this version as the *model version*.
13
13
14
-
The versioning of all three of these entity types is distinct, and largely independent. That is, the ONNX IR format evolves at a different rate than the set operators defined by ONNX – in which the former will version much slower than the latter.
14
+
The versioning of all three of these entity types is distinct and largely independent. That is, the ONNX IR format evolves at a different rate than the set operators defined by ONNX – in which the former will version much slower than the latter.
15
15
16
-
While the versioning mechanisms are clearly specified in this document, the policies for version management are only mandated for IR version and operator version.
16
+
While the versioning mechanisms are clearly specified in this document, specific policies for version management are mandated only for IR version and operator version. For model versioning, they are merely recommendations. For model version, ONNX users and systems MAY follow whichever local customs make sense; however, to facilitate easily managing shared collections of ONNX models, they SHOULD adhere to the policies described under model versioning.
17
17
18
-
For model version, ONNX users and systems MAY follow whichever local customs make sense, however, to facilitate shared libraries or repositories of ONNX models to be manageable, models SHOULD adhere to the policies described under model versioning.
18
+
In addition to versioning ONNX entities, progressive ONNX _releases_ are assigned increasing version numbers. The release versioning scheme is not described as part of the standard itself. It is discussed in the [ONNX release management document](../RELEASE-MANAGEMENT.md).
19
19
20
-
### SemVer, Files and Frameworks
20
+
### Semantic Versioning or Simple Numbers?
21
+
22
+
The ONNX versioning system allows for simple monotonically increasing numbers or semantic versioning. For IR and operator sets, versioning is based on simple numbers. For models, ONNX does not proscribe one or the other methodology, but (as stated earlier) recommends a set of shared conventions.
21
23
22
-
ONNX builds on the principles and syntax defined by [SemVer 2.0.0](http://semver.org/spec/v2.0.0.html). Throughout this document, we use the terms *breaking change*, *non-breaking change*, and *patch* consistent with SemVer 2.0.0.
24
+
Which versioning scheme is in use by a model is made clear by inspecting the most significant four bytes, which MUST be non-zero when using semantic versioning and MUST be zero when using simple numbers. In other words, when using semver, at least one of the MAJOR or MINOR numbers must be non-zero.
25
+
26
+
### SemVer, Files and Frameworks
23
27
24
-
The SemVer specification is written in terms of the dependencies between the caller and callee of a given API. With respect to operator definitions, the NodeProto represents the caller, and the operator specification represents the callee.
28
+
For model and release versioning, ONNX builds on the principles and syntax defined by [SemVer 2.0.0](http://semver.org/spec/v2.0.0.html). Throughout this document, we use the terms *breaking change*, *non-breaking change*, and *patch* consistent with SemVer 2.0.0.
25
29
26
30
Because ONNX models are serialized files (not APIs), it's worth making clear how the dependency between a serialized model and a piece of software that consumes that model relate. As a rough approximation, the serialized model plays the role of an API's *callee*, while the consumer of the serialized model plays the role of the API's *caller*.
27
31
@@ -34,23 +38,26 @@ The ONNX versioning principles are based on [Postel's law](https://en.wikipedia.
34
38
The operational rules specifying how the ONNX project is managed are documented [here](../RELEASE-MANAGEMENT.md).
35
39
36
40
### Serializing SemVer version numbers in protobuf
37
-
For efficiency, ONNX serializes the MAJOR, MINOR, and PATCH values as a bit-packed 32-bit integer; the most significant byte is the MAJOR component, the second most significant byte is the MINOR component, the least significant two bytes are the PATCH component.
38
41
39
-
For example, *1.2.345* is represented as *0x01020159*.
42
+
For efficiency, ONNX serializes the MAJOR, MINOR, and PATCH values as a bit-packed 64-bit integer; the two most significant byte is the MAJOR component, the second two most significant byte is the MINOR component, the least significant four bytes are the PATCH component.
40
43
41
-
The prerelease and build metadata aren't stored in the model.
44
+
For example, *1.2.345* is represented as *0x0001000200000159*.
45
+
46
+
Pre-release and build metadata are not stored in the model.
42
47
43
48
## IR versioning
44
49
45
-
Changes to the file format or abstract graph semantics version atomically. Breaking changes to the format or semantics of the ONNX specification require an increment of the MAJOR version. Non-breaking format or semantic changes that introduce new functionality require an increment of the MINOR version. Non-breaking changes to the specification that simply clarify spec ambiguities require an increment of the PATCH version.
50
+
The IR file format is versioned using simple numbers, which MUST be monotonically increasing. Breaking changes to the format or semantics of the ONNX specification require an increment of the version. Non-breaking changes to the IR format do not require changing the version number.
51
+
52
+
NOTE: breaking changes include those that do not alter the serialized binary format, but still break software using libraries that write or read it. For example, changing the spelling of a message property will cause code accessing the property break.
46
53
47
54
The ONNX IR format adheres to the versioning guidelines defined in the [Updating a Message Type](https://developers.google.com/protocol-buffers/docs/proto3#updating) section of the proto3 specification.
48
55
49
-
As a general principle, implementations SHOULD be robust in the face of missing fields. However, to ensure basic interoperation, a subset of message fields will be marked as required for a given IR version and all producers MUST set these fields correctly. Required fields always are marked with the comment:
56
+
As a general principle, implementations SHOULD be robust in the face of missing fields. However, to ensure basic interoperation, a subset of message fields will be marked as required for a given IR version and all producers MUST set these fields correctly. Required fields MUST always be marked with the comment:
50
57
51
58
// This field MUST be present for this version of the IR.
52
59
53
-
For example, the `ModelProto.ir_version` MUST be present in every model. The ONNX checker (`onnx/checker.py`) will enforce these rules.
60
+
For example, the `ModelProto.ir_version`property MUST be present in every model. The ONNX checker (`onnx/checker.py`) will enforce these rules.
54
61
55
62
Because onnx.proto is expected to be consumed by multiple independent developers, changes to onnx.oroto SHOULD NOT break code that depends on generated language bindings (e.g., changing the type of an existing field).
56
63
@@ -92,27 +99,24 @@ operator id MUST be greater than any extant `op_version` for the
92
99
> 3. Update the `SinceVersion` signifier to the new max version from
93
100
> step (1).
94
101
95
-
ONNX uses operator sets to group together immutable operator specifications. An ONNX operator set
96
-
specifies both the domain of all operators it includes, as well as an opset version. The opset version is largely independent from the version field of the operators it includes. When the inventory of a given operator set changes either by addition or removal, its opset version MUST increase. Moreover,
97
-
the opset version MUST be no less than the highest operator version number in the set.
102
+
ONNX uses operator sets to group together immutable operator specifications. An ONNX operator set specifies both the domain of all operators it includes, as well as an opset version. The opset version is largely independent from the version field of the operators it includes. When the inventory of a given operator set changes either by addition or removal, its opset version MUST increase. Moreover, the opset version MUST be no less than the highest operator version number in the set.
98
103
99
-
ONNX models declare which operator sets they require as a list of two part operator ids (domain, opset_version). The empty string ("") domain indicates the operators defined as part of the
100
-
ONNX specification; other domains correspond to operator sets of other vendors (e.g., they can be used to provide vendor-specific extensions to ONNX). The union of the operator sets specified by a given model MUST have a compatible operator declaration for each node in the model's graph.
104
+
ONNX models declare which operator sets they require as a list of two part operator ids (domain, opset_version). The empty string ("") domain indicates the operators defined as part of the ONNX specification; other domains correspond to operator sets of other vendors (e.g., they can be used to provide vendor-specific extensions to ONNX). The union of the operator sets specified by a given model MUST have a compatible operator declaration for each node in the model's graph.
101
105
102
106
How nodes bind to operator declarations is strictly defined, and are designed to increase model compatibility across ONNX implementations (appealing to the conservative clause of the robustness principle).
103
107
104
-
How ONNX implementations bind an operator declaration to specific implementation is outside the scope of this specification.
105
-
Implementations of ONNX MAY elect to introduce more sophisticated operator declaration/implementation binding modes to appeal to the liberal clause of the robustness principle.
108
+
How ONNX implementations bind an operator declaration to specific implementation is outside the scope of this specification. Implementations of ONNX MAY elect to introduce more sophisticated operator declaration/implementation binding modes to appeal to the liberal clause of the robustness principle.
106
109
107
110
## Model versioning
108
111
109
-
Model versioning is ultimately the domain of a given organization, and therefor, this section of the specification is non-normative and simply proposes a set of practices to consider.
112
+
Model versioning is ultimately the domain of a given organization. Therefore, this section of the specification is not normative. It simply outlines a set of recommended practices.
110
113
111
114
Model authors and applications/systems MAY elect to ignore the model versioning mechanism and policy rules. For models that will be shared across developers, teams, or organizations, model authors and applications/systems SHOULD adhere to the following version policies:
112
115
113
116
ISSUE: the following is a strawman. I'm confident some of it is right and some is wrong. Either way, we need to make some calls and document it. Also note that A LOT of this will likely apply to operators, as both operators and graphs have signatures AND can be versioned.
114
117
115
118
### Signature Changes
119
+
116
120
1. Breaking changes to the ModelProto.graph.GraphProto.input or .output MUST increment the MAJOR version of `ModelProto.model_version`. Breaking changes include:
117
121
118
122
* Breaking changes to the semantics of an input or output (e.g., changing the required contents of an input tensor from a color image to a black and white image).
0 commit comments