1# Versioning
2
3This document describes the versioning policy for this repository. This policy
4is designed so the following goals can be achieved.
5
6**Users are provided a codebase of value that is stable and secure.**
7
8## Policy
9
10* Versioning of this project will be idiomatic of a Go project using [Go
11 modules](https://github.com/golang/go/wiki/Modules).
12 * [Semantic import
13 versioning](https://github.com/golang/go/wiki/Modules#semantic-import-versioning)
14 will be used.
15 * Versions will comply with [semver
16 2.0](https://semver.org/spec/v2.0.0.html) with the following exceptions.
17 * New methods may be added to exported API interfaces. All exported
18 interfaces that fall within this exception will include the following
19 paragraph in their public documentation.
20
21 > Warning: methods may be added to this interface in minor releases.
22
23 * If a module is version `v2` or higher, the major version of the module
24 must be included as a `/vN` at the end of the module paths used in
25 `go.mod` files (e.g., `module go.opentelemetry.io/otel/v2`, `require
26 go.opentelemetry.io/otel/v2 v2.0.1`) and in the package import path
27 (e.g., `import "go.opentelemetry.io/otel/v2/trace"`). This includes the
28 paths used in `go get` commands (e.g., `go get
29 go.opentelemetry.io/otel/v2@v2.0.1`). Note there is both a `/v2` and a
30 `@v2.0.1` in that example. One way to think about it is that the module
31 name now includes the `/v2`, so include `/v2` whenever you are using the
32 module name).
33 * If a module is version `v0` or `v1`, do not include the major version in
34 either the module path or the import path.
35 * Modules will be used to encapsulate signals and components.
36 * Experimental modules still under active development will be versioned at
37 `v0` to imply the stability guarantee defined by
38 [semver](https://semver.org/spec/v2.0.0.html#spec-item-4).
39
40 > Major version zero (0.y.z) is for initial development. Anything MAY
41 > change at any time. The public API SHOULD NOT be considered stable.
42
43 * Mature modules for which we guarantee a stable public API will be versioned
44 with a major version greater than `v0`.
45 * The decision to make a module stable will be made on a case-by-case
46 basis by the maintainers of this project.
47 * Experimental modules will start their versioning at `v0.0.0` and will
48 increment their minor version when backwards incompatible changes are
49 released and increment their patch version when backwards compatible
50 changes are released.
51 * All stable modules that use the same major version number will use the
52 same entire version number.
53 * Stable modules may be released with an incremented minor or patch
54 version even though that module has not been changed, but rather so
55 that it will remain at the same version as other stable modules that
56 did undergo change.
57 * When an experimental module becomes stable a new stable module version
58 will be released and will include this now stable module. The new
59 stable module version will be an increment of the minor version number
60 and will be applied to all existing stable modules as well as the newly
61 stable module being released.
62* Versioning of the associated [contrib
63 repository](https://github.com/open-telemetry/opentelemetry-go-contrib) of
64 this project will be idiomatic of a Go project using [Go
65 modules](https://github.com/golang/go/wiki/Modules).
66 * [Semantic import
67 versioning](https://github.com/golang/go/wiki/Modules#semantic-import-versioning)
68 will be used.
69 * Versions will comply with [semver 2.0](https://semver.org/spec/v2.0.0.html).
70 * If a module is version `v2` or higher, the
71 major version of the module must be included as a `/vN` at the end of the
72 module paths used in `go.mod` files (e.g., `module
73 go.opentelemetry.io/contrib/instrumentation/host/v2`, `require
74 go.opentelemetry.io/contrib/instrumentation/host/v2 v2.0.1`) and in the
75 package import path (e.g., `import
76 "go.opentelemetry.io/contrib/instrumentation/host/v2"`). This includes
77 the paths used in `go get` commands (e.g., `go get
78 go.opentelemetry.io/contrib/instrumentation/host/v2@v2.0.1`. Note there
79 is both a `/v2` and a `@v2.0.1` in that example. One way to think about
80 it is that the module name now includes the `/v2`, so include `/v2`
81 whenever you are using the module name).
82 * If a module is version `v0` or `v1`, do not include the major version
83 in either the module path or the import path.
84 * In addition to public APIs, telemetry produced by stable instrumentation
85 will remain stable and backwards compatible. This is to avoid breaking
86 alerts and dashboard.
87 * Modules will be used to encapsulate instrumentation, detectors, exporters,
88 propagators, and any other independent sets of related components.
89 * Experimental modules still under active development will be versioned at
90 `v0` to imply the stability guarantee defined by
91 [semver](https://semver.org/spec/v2.0.0.html#spec-item-4).
92
93 > Major version zero (0.y.z) is for initial development. Anything MAY
94 > change at any time. The public API SHOULD NOT be considered stable.
95
96 * Mature modules for which we guarantee a stable public API and telemetry will
97 be versioned with a major version greater than `v0`.
98 * Experimental modules will start their versioning at `v0.0.0` and will
99 increment their minor version when backwards incompatible changes are
100 released and increment their patch version when backwards compatible
101 changes are released.
102 * Stable contrib modules cannot depend on experimental modules from this
103 project.
104 * All stable contrib modules of the same major version with this project
105 will use the same entire version as this project.
106 * Stable modules may be released with an incremented minor or patch
107 version even though that module's code has not been changed. Instead
108 the only change that will have been included is to have updated that
109 modules dependency on this project's stable APIs.
110 * When an experimental module in contrib becomes stable a new stable
111 module version will be released and will include this now stable
112 module. The new stable module version will be an increment of the minor
113 version number and will be applied to all existing stable contrib
114 modules, this project's modules, and the newly stable module being
115 released.
116 * Contrib modules will be kept up to date with this project's releases.
117 * Due to the dependency contrib modules will implicitly have on this
118 project's modules the release of stable contrib modules to match the
119 released version number will be staggered after this project's release.
120 There is no explicit time guarantee for how long after this projects
121 release the contrib release will be. Effort should be made to keep them
122 as close in time as possible.
123 * No additional stable release in this project can be made until the
124 contrib repository has a matching stable release.
125 * No release can be made in the contrib repository after this project's
126 stable release except for a stable release of the contrib repository.
127* GitHub releases will be made for all releases.
128* Go modules will be made available at Go package mirrors.
129
130## Example Versioning Lifecycle
131
132To better understand the implementation of the above policy the following
133example is provided. This project is simplified to include only the following
134modules and their versions:
135
136* `otel`: `v0.14.0`
137* `otel/trace`: `v0.14.0`
138* `otel/metric`: `v0.14.0`
139* `otel/baggage`: `v0.14.0`
140* `otel/sdk/trace`: `v0.14.0`
141* `otel/sdk/metric`: `v0.14.0`
142
143These modules have been developed to a point where the `otel/trace`,
144`otel/baggage`, and `otel/sdk/trace` modules have reached a point that they
145should be considered for a stable release. The `otel/metric` and
146`otel/sdk/metric` are still under active development and the `otel` module
147depends on both `otel/trace` and `otel/metric`.
148
149The `otel` package is refactored to remove its dependencies on `otel/metric` so
150it can be released as stable as well. With that done the following release
151candidates are made:
152
153* `otel`: `v1.0.0-RC1`
154* `otel/trace`: `v1.0.0-RC1`
155* `otel/baggage`: `v1.0.0-RC1`
156* `otel/sdk/trace`: `v1.0.0-RC1`
157
158The `otel/metric` and `otel/sdk/metric` modules remain at `v0.14.0`.
159
160A few minor issues are discovered in the `otel/trace` package. These issues are
161resolved with some minor, but backwards incompatible, changes and are released
162as a second release candidate:
163
164* `otel`: `v1.0.0-RC2`
165* `otel/trace`: `v1.0.0-RC2`
166* `otel/baggage`: `v1.0.0-RC2`
167* `otel/sdk/trace`: `v1.0.0-RC2`
168
169Notice that all module version numbers are incremented to adhere to our
170versioning policy.
171
172After these release candidates have been evaluated to satisfaction, they are
173released as version `v1.0.0`.
174
175* `otel`: `v1.0.0`
176* `otel/trace`: `v1.0.0`
177* `otel/baggage`: `v1.0.0`
178* `otel/sdk/trace`: `v1.0.0`
179
180Since both the `go` utility and the Go module system support [the semantic
181versioning definition of
182precedence](https://semver.org/spec/v2.0.0.html#spec-item-11), this release
183will correctly be interpreted as the successor to the previous release
184candidates.
185
186Active development of this project continues. The `otel/metric` module now has
187backwards incompatible changes to its API that need to be released and the
188`otel/baggage` module has a minor bug fix that needs to be released. The
189following release is made:
190
191* `otel`: `v1.0.1`
192* `otel/trace`: `v1.0.1`
193* `otel/metric`: `v0.15.0`
194* `otel/baggage`: `v1.0.1`
195* `otel/sdk/trace`: `v1.0.1`
196* `otel/sdk/metric`: `v0.15.0`
197
198Notice that, again, all stable module versions are incremented in unison and
199the `otel/sdk/metric` package, which depends on the `otel/metric` package, also
200bumped its version. This bump of the `otel/sdk/metric` package makes sense
201given their coupling, though it is not explicitly required by our versioning
202policy.
203
204As we progress, the `otel/metric` and `otel/sdk/metric` packages have reached a
205point where they should be evaluated for stability. The `otel` module is
206reintegrated with the `otel/metric` package and the following release is made:
207
208* `otel`: `v1.1.0-RC1`
209* `otel/trace`: `v1.1.0-RC1`
210* `otel/metric`: `v1.1.0-RC1`
211* `otel/baggage`: `v1.1.0-RC1`
212* `otel/sdk/trace`: `v1.1.0-RC1`
213* `otel/sdk/metric`: `v1.1.0-RC1`
214
215All the modules are evaluated and determined to a viable stable release. They
216are then released as version `v1.1.0` (the minor version is incremented to
217indicate the addition of new signal).
218
219* `otel`: `v1.1.0`
220* `otel/trace`: `v1.1.0`
221* `otel/metric`: `v1.1.0`
222* `otel/baggage`: `v1.1.0`
223* `otel/sdk/trace`: `v1.1.0`
224* `otel/sdk/metric`: `v1.1.0`