VERSIONING.md (10988B)
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/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 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`