| 1 |
# Versioning |
| 2 |
|
| 3 |
This document describes the versioning policy for this repository. This policy |
| 4 |
is 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/[email protected]`). 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/[email protected]`. 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 dashboards. |
| 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 |
|
| 132 |
To better understand the implementation of the above policy the following |
| 133 |
example is provided. This project is simplified to include only the following |
| 134 |
modules 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 |
|
| 143 |
These 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 |
| 145 |
should be considered for a stable release. The `otel/metric` and |
| 146 |
`otel/sdk/metric` are still under active development and the `otel` module |
| 147 |
depends on both `otel/trace` and `otel/metric`. |
| 148 |
|
| 149 |
The `otel` package is refactored to remove its dependencies on `otel/metric` so |
| 150 |
it can be released as stable as well. With that done the following release |
| 151 |
candidates 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 |
|
| 158 |
The `otel/metric` and `otel/sdk/metric` modules remain at `v0.14.0`. |
| 159 |
|
| 160 |
A few minor issues are discovered in the `otel/trace` package. These issues are |
| 161 |
resolved with some minor, but backwards incompatible, changes and are released |
| 162 |
as 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 |
|
| 169 |
Notice that all module version numbers are incremented to adhere to our |
| 170 |
versioning policy. |
| 171 |
|
| 172 |
After these release candidates have been evaluated to satisfaction, they are |
| 173 |
released 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 |
|
| 180 |
Since both the `go` utility and the Go module system support [the semantic |
| 181 |
versioning definition of |
| 182 |
precedence](https://semver.org/spec/v2.0.0.html#spec-item-11), this release |
| 183 |
will correctly be interpreted as the successor to the previous release |
| 184 |
candidates. |
| 185 |
|
| 186 |
Active development of this project continues. The `otel/metric` module now has |
| 187 |
backwards 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 |
| 189 |
following 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 |
|
| 198 |
Notice that, again, all stable module versions are incremented in unison and |
| 199 |
the `otel/sdk/metric` package, which depends on the `otel/metric` package, also |
| 200 |
bumped its version. This bump of the `otel/sdk/metric` package makes sense |
| 201 |
given their coupling, though it is not explicitly required by our versioning |
| 202 |
policy. |
| 203 |
|
| 204 |
As we progress, the `otel/metric` and `otel/sdk/metric` packages have reached a |
| 205 |
point where they should be evaluated for stability. The `otel` module is |
| 206 |
reintegrated 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 |
|
| 215 |
All the modules are evaluated and determined to a viable stable release. They |
| 216 |
are then released as version `v1.1.0` (the minor version is incremented to |
| 217 |
indicate 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` |